deployment.toml

deployment.toml is the operator's file. It lists the agents one vessel serves, grants each one its data, services and sandbox limits, and says who may call which agent. It is the only place access is granted. Types, defaults and constraints for every key are generated from the code in Configuration tables.

A complete example

[vessel]
project = "astralvessel"
public_url = "http://vessel:8700"
front_subnet = "172.31.247.0/24"
front_address = "172.31.247.10"
task_ttl_hours = 24

[egress]
upstream_url = "env:VESSEL_UPSTREAM_MODEL_URL"
upstream_key = "env:VESSEL_UPSTREAM_MODEL_KEY"

[search]
provider = "searxng"

[[agents]]
id = "field-guide"
package = "../examples/field-guide"
[agents.sandbox]
memory = "1g"
cpus = 2
pids = 256
scratch = "64m"
mounts = [{ target = "/data", source = "../examples/sample-data" }]

[[apps]]
name = "example"
key_sha256 = "env:VESSEL_APP_KEY_SHA256"
agents = ["field-guide"]

Relative paths (package, mount sources, jwks_file) are relative to the deployment file. Unknown keys are refused.

[vessel]

Key	Meaning
project	The Compose project name. It prefixes containers, networks, volumes and locally built images. See Several deployments on one host.
public_url	The base URL written into agent cards and the agent list. Set it to the address your callers use.
front_subnet	The subnet of the internal front network, a /28 or larger. Other containers that join it get addresses from its upper half only.
front_address	The vessel's fixed address on front, in the lower half of front_subnet; it listens only there, on port 8700.
task_ttl_hours	Task records not updated for this long are deleted, checked hourly.

[egress]

Key	Meaning
upstream_url	Your OpenAI-compatible base URL, such as https://api.example.com/v1, or env:NAME.
upstream_key	The model key, normally as env:NAME.

See Models and egress.

[search]

Key	Meaning
provider	searxng runs a private SearXNG container; duckduckgo scrapes DuckDuckGo's HTML page. See Search.

[[agents]]

Key	Meaning
id	Lowercase letters, digits and hyphens, starting with a letter. The agent's address is /agents/<id>.
package	The agent folder.
prompt_append	Extra briefing files from the folder, appended after prompt.md. See Prompts.
model	The model this agent uses, overriding the model its vessel.toml names. astralvessel up writes it.
sandbox	The sandbox profile.
services	Service grants, one per service the agent's tools name. See Service tools.

[agents.sandbox]

Key	Meaning
mounts	{ target, source, read_only } grants, one for each mount the agent declares.
memory	The container's memory limit.
cpus	CPU limit; greater than 0.
pids	Process limit; at least 32.
scratch	Size of the sandbox's /tmp, which holds every turn's workspace.
turn_disk	Disk one turn may use; a quarter of scratch unless set. See Disk limits.
user_disk	Disk one user's live turns may use together; half of scratch unless set.

A mount source can be:

Form	Meaning
A relative path	Relative to the deployment file
An absolute path	Used as is
env:NAME	Filled from the environment by Compose
volume:NAME	An existing Docker volume, for data another stack writes; declared external in the Compose file

Every grant must be read-only and its target must match a mount the agent declares, and the agent's declared mounts must all be granted.

[[apps]]

Key	Meaning
name	Lowercase letters, digits and hyphens, starting with a letter; unique. Appears in task owners as <name>/<user>.
key_sha256	The hex SHA-256 of the app's key, or env:NAME. The vessel never holds the key itself.
agents	The agent ids this app may call.

[[issuers]]

Token issuers callers may authenticate with instead of an app key. See Identity, apps and issuers.

A deployment needs at least one app or issuer.

env: values

Settings marked as accepting env:NAME stay references in the generated Compose file (${NAME:?...}), so secrets are never copied into it. Compose fills them from the environment or from the --env-file you pass, and refuses to start if one is unset.

Check a file

python -c 'from astralvessel.deployment import load_deployment; d = load_deployment("deployment.toml"); print(list(d.agents))'

This loads every agent folder and checks every grant, as deploy does.