Reference

agent.toml

A fly.toml-style declaration of your agent. Optional at every layer — sky launch scaffolds it, a flags-only path exists for everything, and the file never crosses the wire (the CLI validates and inlines it client-side).

Full schema

Only name is required; type defaults to hermes and llmto the type's default model. Long markdown can live inline in triple-quoted strings or in sibling files via file = / prompt_file = — the CLI inlines their content before calling the API.

toml

# agent.toml — everything the create wizard can set. Only `name` is required.
name = "research-agent"
description = "Web research with citations"
type = "hermes"                    # hermes | claude_code | codex | openclaw | pi | dsh
llm = "deepseek-flash"             # must be compatible with type
capabilities = ["exa.search"]      # capability ids from the catalog
vcpus = 2                          # optional machine size for launch's first session: 1|2|4|8
memory_mb = 4096                   # 256MB steps, 256-2048MB per vCPU

# The user prompt layer; the platform preamble is composed server-side.
# Inline here, or `prompt_file = "prompt.md"`.
prompt = """
You are a meticulous research agent…
"""

[[instructions]]                   # additional .md files for the agent
name = "style.md"
file = "instructions/style.md"     # or inline: content = """…"""

[[skills]]                         # a store skill, attached by reference
type = "skill"
skillId = "skill_…"                # from POST /v1/skills
version = "latest"                 # or a revision id (skr_…) to pin

[[skills]]                         # or a GitHub repo: its root .claude/skills/
type = "github"                    # is loaded at every session start
url = "https://github.com/org/repo"
ref = "main"                       # optional branch or commit SHA

[[customData]]
id = "prices"
name = "Price sheet"
kind = "spreadsheet"               # spreadsheet | doc | private_api | other
uri = "https://…"

Secrets are not spec data — set them after launch with sky secrets set <id> KEY=VALUE (values are write-only, encrypted at rest).

Lifecycle

sky launch creates the agent spec + its first session and stamps id = "agent_…" (the agent id — session ids never live in the file); from then on sky deploy re-applies your edits (prompt, display name, capabilities) to the spec, idempotently — the prompt applies to sessions started after the save. -f <path> overrides the ./agent.toml discovery on both commands.

Full schema#

Lifecycle#

Full schema

Lifecycle