Container tools

The running containers of a deployment: listing, inspecting, reading output, and the three operations that change one.

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
container_exec	containers:exec	operator	no
container_inspect	containers:read	developer, operator, readonly, support	no
container_list	containers:read	developer, operator, readonly, support	yes
container_logs	containers:logs	developer, operator, support	yes
container_remove	containers:manage	operator	no
container_restart	containers:restart	—	no
container_stop	containers:stop	—	no

container_exec

Execute a command inside a running container. Commands are classified into three tiers: (1) allowed - safe diagnostic commands auto-execute, (2) requires_approval - user must approve before execution, (3) denied - destructive commands are never allowed. Use ‘approved: true’ to execute a previously approved command.

Argument	Type	Required	Meaning
container_id	string	yes	Container ID or name
command	string	yes	Command to execute inside the container
approved	boolean	no	Set to true if user has approved this command. Skips classification and executes directly.

container_inspect

Get detailed information about a container including configuration, state, and network settings

Argument	Type	Required	Meaning
container_id	string	yes	Container ID or name

container_list

List all containers, optionally filtered by deployment or status. Use format=‘summary’ (default) for minimal output, ‘standard’ for operational details, or ‘full’ for complete data. Use container_inspect for full details on a specific container.

Argument	Type	Required	Meaning
deployment	string	no	Filter by deployment name
status	one of all, running, stopped, unhealthy	no	Filter by container status
include_unmanaged	boolean	no	Include containers not managed by Odysseus (default: false, only shows Odysseus-managed containers)
format	one of summary, standard, full	no	Response detail level: ‘summary’ (minimal), ‘standard’ (operational), ‘full’ (complete). Default: summary

container_logs

Retrieve logs from a container. Returns last 100 lines by default. Use tail parameter for more lines (max 1000). Use search/level filters to find specific issues.

Argument	Type	Required	Meaning
container_id	string	no	Container ID or name
deployment	string	no	Alternative: deployment name (returns logs from all replicas)
tail	integer	no	Number of lines from end (default: 100, max: 1000)
since	string	no	Show logs since timestamp or duration (e.g., ‘10m’, ‘1h’, ‘2026-01-11T10:00:00Z’)
search	string	no	Filter logs containing this string
level	one of all, error, warn, info, debug	no	Filter by log level (if logs are structured)

container_remove

Stop and permanently remove a container. Use this to clean up orphaned containers or remove containers that are no longer needed.

Argument	Type	Required	Meaning
container_id	string	yes	Container ID or name to remove
confirm	boolean	yes	Must be true to proceed with removal

container_restart

Restart a specific container

Argument	Type	Required	Meaning
container_id	string	yes	Container ID or name
timeout	integer	no	Seconds to wait before force kill

container_stop

Stop a specific container. For stopping all replicas, use deployment_scale with replicas=0

Argument	Type	Required	Meaning
container_id	string	yes	Container ID or name
timeout	integer	no	Seconds to wait before force kill
confirm	boolean	yes	Must be true. Stopping a container halts a running workload and is not silently reversible from the caller’s point of view.