Deployment tools

Creating, reading, changing, scaling, restarting and rolling back a deployment, and driving a canary release.

Permission is what the tool server requires before it dispatches; who holds it is read from the control plane’s own grant. The two are read from different places on purpose: a tool server that grants more than the control plane does offers an operation and then has it refused halfway through a conversation.

Advertised says whether the tool appears in the default tool list. Most do not: a small window is advertised and the rest are found with search_tools, read with describe_tool and invoked with request_tool. A tool reached that way is checked against the same permission as a direct call.

Generated from Tool. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

Tool	Permission	Who holds it	Advertised
canary_pause	deployments:update	developer, operator	no
canary_promote	deployments:update	developer, operator	no
canary_resume	deployments:update	developer, operator	no
canary_rollback	deployments:rollback	operator	no
canary_start	deployments:update	developer, operator	no
canary_status	deployments:read	developer, operator, readonly, support	no
config_scaling	config:write	an administrator only, through the wildcard grant	no
config_validate	config:read	developer, operator, readonly, support	no
config_view	config:read	developer, operator, readonly, support	no
deployment_create	deployments:create	developer	no
deployment_delete	deployments:delete	developer	no
deployment_get	deployments:read	developer, operator, readonly, support	yes
deployment_history	deployments:read	developer, operator, readonly, support	no
deployment_list	deployments:read	developer, operator, readonly, support	yes
deployment_restart	deployments:restart	operator	no
deployment_rollback	deployments:rollback	operator	no
deployment_scale	deployments:scale	operator	no
deployment_secrets_rotate	vault:manage	developer	no
deployment_update	deployments:update	developer, operator	no
image_list	images:read	developer, operator, readonly, support	no

canary_pause

Pause canary progression at current weight for investigation

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment

canary_promote

Immediately promote canary to full traffic, completing the deployment

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment
confirm	boolean	yes	Must be true to proceed

canary_resume

Resume paused canary progression

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment

canary_rollback

Immediately rollback canary, returning all traffic to stable version

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment
reason	string	no	Reason for rollback (logged)

canary_start

Start a canary deployment to test a new image version with gradual traffic shifting. Routes a percentage of traffic to the new version while keeping the stable version running.

Argument	Type	Required	Meaning
deployment	string	yes	Name of the deployment to create a canary for
newImage	string	yes	The new container image to test (e.g., ‘nginx:1.25.0’, ‘myapp:v2.1.0’)
initialWeight	number	no	Initial percentage of traffic to route to the canary (1-50, default 10)
stepWeight	number	no	Percentage to increase canary traffic by on each step (default 10)
stepInterval	string	no	Duration between weight increases (e.g., ‘5m’, ‘30m’, ‘1h’). Default ‘5m’
successThreshold	number	no	Minimum success rate (0-100) required to continue progression. Default 95

canary_status

Get current canary deployment status including traffic weight, metrics comparison, and progression

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment with active canary

config_scaling

Update autoscaling configuration for a deployment. Changes take effect immediately.

Argument	Type	Required	Meaning
deployment	string	yes	Name of deployment to configure
min	integer	no	Minimum replica count
max	integer	no	Maximum replica count
enabled	boolean	no	Enable or disable autoscaling
target_cpu	integer	no	Target CPU utilization percentage for scaling
target_memory	integer	no	Target memory utilization percentage for scaling
scale_up_cooldown	integer	no	Seconds to wait between scale-up events
scale_down_cooldown	integer	no	Seconds to wait between scale-down events

config_validate

Validate a deployment manifest without applying it. Checks syntax, references, and resource constraints.

Argument	Type	Required	Meaning
manifest	string	no	YAML manifest content to validate
manifest_path	string	no	Path to manifest file (alternative to inline manifest)
strict	boolean	no	Enable strict validation (warnings become errors)

config_view

View current Odysseus configuration. Returns sanitized configuration without sensitive values.

Argument	Type	Required	Meaning
section	one of all, scaling, security, logging, node	no	Configuration section to view

deployment_create

Create a new deployment from a specification. For complex deployments, prefer uploading a manifest file. Sensitive configuration goes in secrets (Vault-backed, env-delivered), never in environment. Inline secret values cannot be supplied here — use secrets[].generate, or reference an existing document by vault_path.

Argument	Type	Required	Meaning
dry_run	boolean	no	Validate without creating

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.

deployment_delete

Delete a deployment and all its containers. This action cannot be undone.

Argument	Type	Required	Meaning
name	string	yes	Name of deployment to delete
confirm	boolean	yes	Must be true to proceed with deletion
force	boolean	no	Force deletion even if containers are unhealthy

deployment_get

Get detailed information about a specific deployment including configuration, scaling policy, and container instances

Argument	Type	Required	Meaning
name	string	yes	Name of the deployment to retrieve
include_containers	boolean	no	Include individual container details
include_scaling	boolean	no	Include scaling policy and metrics
include_events	boolean	no	Include recent events (last 20)

deployment_history

View revision history for a deployment

Argument	Type	Required	Meaning
name	string	yes	Name of deployment
limit	integer	no	Maximum revisions to return

deployment_list

List all deployments managed by Odysseus with their current status, replica counts, and health. Use format=‘summary’ (default) for minimal output, ‘standard’ for operational details, or ‘full’ for complete data. Use deployment_get for full details on a specific deployment.

Argument	Type	Required	Meaning
status_filter	one of all, running, degraded, stopped, updating	no	Filter by deployment status
labels	object	no	Filter by deployment labels (key-value pairs)
format	one of summary, standard, full	no	Response detail level: ‘summary’ (minimal), ‘standard’ (operational), ‘full’ (complete). Default: summary

deployment_restart

Perform a rolling restart of all containers in a deployment. Maintains availability during restart.

Argument	Type	Required	Meaning
name	string	yes	Name of the deployment to restart
strategy	one of rolling, all	no	Restart strategy: rolling (one at a time) or all (simultaneously)
reason	string	no	Reason for restart (logged for audit)

deployment_rollback

Rollback a deployment to a previous revision. Lists available revisions if revision not specified.

Argument	Type	Required	Meaning
name	string	yes	Name of the deployment to rollback
revision	integer	no	Target revision number. Omit to see available revisions.
confirm	boolean	no	Confirm rollback. Required when revision is specified.

deployment_scale

Scale a deployment to a specific number of replicas. Validates against min/max bounds if autoscaling is configured.

Argument	Type	Required	Meaning
name	string	yes	Name of the deployment to scale
replicas	integer	yes	Target number of replicas
reason	string	no	Reason for scaling (logged for audit)

deployment_secrets_rotate

Make one deployment re-resolve its secret references: the platform verifies every ref resolves in Vault, then bumps the deployment’s secretsVersion so its containers are recreated against the current material. Use this after material was written out of band (dashboard or PUT /api/v1/secrets/{resource}) — a running container will not otherwise see a new value. It recreates containers, so it is a service-affecting operation.

Argument	Type	Required	Meaning
name	string	yes	Name of the deployment whose secrets should be re-resolved.

deployment_update

Update a deployment’s image, environment, secrets, or configuration. Triggers rolling update. Sensitive configuration belongs in secrets, not environment. Inline secret values cannot be supplied here.

Argument	Type	Required	Meaning
remove_environment	array	no	Environment variable names to remove

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.

image_list

List all Docker images available on the host. Use this to discover what container images are available for deployments. Returns image names with tags (e.g., ‘nginx:latest’, ‘postgres:16-alpine’).

Takes no arguments.