Quickstart

Deploy your first agent to every tenant

Scaffold an agent, deploy it once for every tenant on your platform, run it, and open the result in the Console. About ten minutes, four commands.

• tanomis installed and signed in as a platform operator (Get access)
• Python 3.12 or newer and uv on your PATH
• A directory in your own repository

The journey is Prepare → Scaffold → Validate → Deploy → Run.

1. 1PrepareSigned in, tenants listed1 min
2. 2ScaffoldA working agent1 min
3. 3ValidateA dry run, nothing uploaded1 min
4. 4DeployOne version, all tenants3–5 min
5. 5RunA governed run1 min

1. Check you are signed in

Confirm the context, and see the tenants the deploy will reach:

Terminal

tanomis auth status
tanomis tenant ls

Output

context: saas   logged-in: yes   expires in 54m

TENANT               STATE
northwind-sandbox    active
bluewater-bank       active
orion-retail         active
helix-health         active

Checkpoint: signed in. You should see logged-in: yes and at least one active tenant. Your customers are tenants; the sandbox is the one that serves no customer, and it is where you will run the agent in step 5.

2. Scaffold a working agent

One command gives you a Claude Agent SDK project that already answers. You will make it yours after it runs.

Terminal

tanomis agent new support-copilot --harness claude-agents-sdk --agents-root ./agents --description "Triage and draft responses to support requests"

agents/support-copilot/
├── agent.py                      create_agent(input, context) returns (prompt, options)
├── agent.yaml                    what the agent may do: model, hosts, tools, limits
├── pyproject.toml
├── uv.lock
└── tests/test_agent_contract.py

Open agent.py and change one line, the system_prompt, to “Triage support requests: severity, summary, and a concise draft reply.” Everything else stays. Then run the contract test:

Terminal

cd agents/support-copilot
uv run python -m unittest tests/test_agent_contract.py

Checkpoint: project ready. You should see OK. The test checks the entrypoint’s shape; your prompt logic is plain Python and needs no runtime to import.

3. Dry-run the deploy

See exactly what would be built and where it would be enabled, without uploading a byte. This is the same command you will put on every pull request.

Terminal

uv lock --locked
tanomis agent deploy . --scope global --tenants all --dry-run

Output

dry-run: tanomis agent deploy .

  name:          support-copilot
  version:       0.1.0
  scope:         global
  tenants:       all (active customer tenants snapshotted by the server)
  build profile: python-managed
  lock policy:   uv-frozen
  files:         5
  checksum:      sha256:9f1c…e2a0

no changes made (dry-run) — no build was created, no bytes were uploaded

Checkpoint: package ready. You should see “no changes made”. Commit uv.lock; remote builds only accept locked projects.

4. Deploy to every tenant

One command builds remotely, registers an immutable global version with the contract you declared, takes a warm-start snapshot, and enables the version for every active tenant. Nothing routes traffic until that last step.

Terminal

tanomis agent deploy . --scope global --tenants all

Output (abridged)

build bld_3f9a2c created for support-copilot@0.1.0 (global, tenants all, profile python-managed, lock uv-frozen)
upload     done
build      done      image sha256:7ab3…
register   done      support-copilot@0.1.0
golden     ready     sessions will warm-start
enable     done      12 tenants → 0.1.0

Not a platform operator? Organization members deploy to their own tenants with --tenant TENANT instead of --scope global --tenants all. The rest of this page is the same.

Confirm what each tenant now serves:

Terminal

tanomis agent versions support-copilot --by-tenant

Checkpoint: version enabled. You should see enable done with the tenant count, and every tenant on 0.1.0 in the versions table. A tenant created later is enabled with tanomis agent enable. A skipped golden is fine: the version still runs, with cold starts.

5. Run it

Invoke the agent in the sandbox tenant through the same managed path the Console and your applications use. The command opens a session, starts a run, and streams its events.

Terminal

tanomis session run support-copilot \
  --tenant northwind-sandbox \
  --prompt "Customer reports that CSV exports stop at 80%. Draft a first response."

Output

session  ses_7d4f9c   run  run_a12bc3   version  support-copilot@0.1.0
run_started      12:04:01
agent_message    Thanks for flagging this. Exports stopping at 80% usually means ...
run_completed    12:04:09   status=succeeded

Checkpoint: first run verified. You should see run_completed with status=succeeded. If the stream closes without it, the run resource in the Console or API is the authority.

Console · Sessions · ses_7d4f9c · run_a12bc3

Open the run in the Console. The same events are there, plus who invoked it, the policy decisions the run passed, and the execution trace. This is the record every run gets; see Tour the Console.

What you just built

The lifecycle from the Overview, with every stage now real.

1. Sourceagents/support-copilot in your repository.
2. Versionsupport-copilot@0.1.0, global, immutable.
3. EnablementEvery customer tenant serves 0.1.0.
4. Sessionses_7d4f9c, warm-started.
5. Runrun_a12bc3, succeeded.
6. EvidenceLedger entry and trace, in the Console.

Next

Make it yoursWrite your agentPrompts, tools, and input handling in agent.py; what the harness gives you.

Give it toolsMCP connectorsDeclare a connector and require confirmation for selected tool calls.

Ship the next versionRoll out and roll backCanary 0.2.0 to a few tenants, graduate it, or restore the baseline in one command.

If something goes wrong

Symptom	Next action
Login required or tenant denied	Run tanomis login, then tanomis auth status. An administrator confirms your grant.
Lockfile missing or stale	Run uv lock, commit uv.lock, repeat the dry run.
Manifest rejected	Restore the generated fields; read Manifest essentials before widening anything.
Build fails after a clean dry run	Read the failing phase in the output, fix the dependency or source error, deploy again.
First run is slow	The golden was skipped; the version cold-starts and is still usable.
A model or tool action is denied	Compare with permitted_models, the approval list, and tenant policy. Refusals are recorded in the run.