llms.txt
Compare with other sites' llms.txt files →# tama
Machines with GPUs, driven from a shell. One binary, no daemon, nothing to configure. A
machine is a Linux VM you can SSH into, run an agent inside, snapshot mid-task, fork and
stop. You are billed for the seconds a machine is running; a stopped machine is billed for
nothing, and stopping snapshots it on the way down.
Read this before the first command. It covers the Python and TypeScript SDKs and the whole
CLI in the order you would use them, then eight tasks worked end to end. Every flag, both
SDK quickstarts, and the lines each command prints are at https://tama.computer/docs
## Rules
- One card per machine. Leave `--gpu-count` at 1: every machine is created with
checkpointing on, checkpointing more than one card is not supported, and a higher count
fails at create rather than coming back as a machine that cannot be stopped.
- Work under `/workspace`. It is the durable 50 GiB disk, every shell starts there, and it
is the only place edits survive a stop.
- Run `tama offers` before `tama new`. It lists the cards that exist, their rate and the
size they come with; a card missing from it is a card `new` will refuse.
- Keys are workspace secrets, never files in the machine. Nothing in a snapshot or a fork
carries a credential.
- `--image` and `--template` are exclusive. A template's disk was built on its own image
and is restored onto it.
- Stopping is free and reversible. `tama rm` is neither, and it is the only command that
destroys a disk.
- `exec`, `ssh` and `prompt` exit with the code of the thing they ran. Branch on the exit
status rather than parsing output.
- A long job should not depend on your connection. Start it with `nohup ... &`, keep the
pid, and follow it with `tama logs`.
- Name a machine after what it is for. Names are how every other command finds it.
## Install and sign in
curl -fsSL https://tama.computer/install | sh
tama login
`tama login` opens a browser, writes the credential to `~/.tama/config.yaml`, and
generates an SSH key and config of its own. It gives up after five minutes. In CI, adopt a
token instead and skip the browser:
tama login --token "$TAMA_TOKEN"
`--api` and `--console` point the CLI somewhere other than production, and fall back to
`TAMA_API` and `TAMA_CONSOLE`.
## Python SDK
Use the Python SDK when Python code should control Tama directly instead of shelling out
to the CLI. It is synchronous and requires Python 3.10 or newer. Install the package:
python -m pip install tama-sdk
The distribution is `tama-sdk`; the import is `tama_sdk`. Do not install `tama` or
`tama-cli`: those are unrelated PyPI projects.
Complete Python-only SDK guide: https://tama.computer/python-sdk.txt
Set `TAMA_TOKEN` and call `Tama()`. `TAMA_API_URL` overrides the production gateway.
Explicit constructor values win over environment variables. Use a raw token; an optional
`Bearer ` prefix is accepted. Never print or log the token:
import os
from tama_sdk import Tama
tama = Tama(api_key=os.environ["TAMA_TOKEN"])
print(tama.identity().account.id)
tama.close()
This is the safe shape for code that creates a billable machine. `check=True` makes a
non-zero remote exit raise `CommandError`. The machine cleanup is separate from closing
the client:
from tama_sdk import Tama
tama = Tama()
machine = tama.new(name="python-sdk-example", auto_stop_seconds=900)
try:
result = machine.exec(["python", "--version"], check=True)
print(result.stdout, end="")
finally:
machine.stop()
tama.close()
`machine.stop()` snapshots the machine and pauses billing. It is reversible with
`machine.start()`. `machine.delete()` and `tama.rm()` permanently destroy the machine;
never substitute either one for cleanup unless destruction was explicitly requested.
The object model is direct:
tama.new(...) # create; waits until ready by default
tama.list(all=True) # include stopped machines
machine = tama.get("worker")
machine.exec(["pytest", "-q"], check=True)
machine.keep_active() # explicit idle-policy heartbeat
machine.stop()
machine.start()
tama.snapshots.create(machine.id, label="baseline")
tama.snapshots.fork(SNAPSHOT_ID, name="attempt-2")
tama.templates.list()
tama.secrets.list()
tama.tokens.list()
tama.files.list(machine.id, "/workspace")
Complete `Tama` surface:
tama.identity() # account identity
tama.usage(days=30) # balance and metered usage
tama.offers() # available machine shapes
tama.new(..., auto_stop_seconds=900) # create; 15-minute idle auto-stop
tama.list(all=False) # list running; all=True includes stopped
tama.get(name_or_id) # resolve one
tama.keep_active(name_or_id) # refresh the idle deadline
tama.rm(name_or_id) # PERMANENT delete
tama.stop(name_or_id, no_snapshot=False)
tama.start(name_or_id, wait=True, timeout=900)
tama.fork(snapshot_id, name="copy", wait=True, timeout=900)
tama.exec(name_or_id, command, cwd="", check=False, timeout=None)
tama.prompt(name_or_id, prompt, agent="claude", cwd="", detach=False, check=False)
tama.logs(session_id) # durable session transcript
tama.logs(machine_id, pid) # low-level process logs
tama.expose(name_or_id, port) # returns HTTPS URL
tama.unexpose(name_or_id, port)
tama.ports(name_or_id) # {port: URL or None}
tama.desktop(name_or_id) # browser desktop URL
tama.terminal(name_or_id) # browser terminal URL
tama.enable_ssh(name_or_id, public_key)
The `Machine` object has `id`, `name`, `status`, `status_detail`, raw protobuf `data`,
and the restore point returned by stop in `snapshot`. Its actions are `refresh`, `exec`,
`prompt`, `stop`, `start`, `delete`, `expose`, `unexpose`, `desktop`, `terminal`, and
`enable_ssh`. Use these scoped methods once you have a machine.
Complete collection surface:
tama.machines.create(...) # also get/list/delete/stop/start
tama.snapshots.create(machine, label="")
tama.snapshots.list(machine="", automatic=False)
tama.snapshots.fork(snapshot_id, name="copy")
tama.templates.create(machine, name="", description="", public=False)
tama.templates.list(); tama.templates.delete(template_id)
tama.secrets.set(name, value); tama.secrets.list(); tama.secrets.delete(name)
created = tama.tokens.create("ci") # created.secret is returned ONCE
tama.tokens.list(); tama.tokens.revoke(created.id)
tama.sessions.list(machine); tama.sessions.logs(session_id)
tama.files.list(machine, path="~")
`tama.start_credit_purchase(amount_cents)` returns a checkout URL and
`tama.confirm_credit_purchase(session_id)` refreshes the balance after checkout. Do not
attempt payment autonomously: send the URL to the human. `tama.raw` is the generated gRPC
stub for forward compatibility; prefer the typed methods above.
Fork, expose, then clean up safely:
with Tama() as tama:
source = tama.get("worker")
snapshot = tama.snapshots.create(source.id, label="before-change")
if snapshot is None:
raise RuntimeError("snapshot was not created")
experiment = tama.snapshots.fork(snapshot.id, name="experiment-1")
try:
experiment.exec(
["sh", "-lc", "python -m http.server 8000 >/tmp/http.log 2>&1 &"],
check=True,
)
print(experiment.expose(8000))
finally:
experiment.stop() # use delete only when destruction is intended
Secondary resources are on `tama.snapshots`, `tama.templates`, `tama.secrets`,
`tama.tokens`, `tama.sessions`, and `tama.files`. `TamaError` is the base SDK exception;
specific subclasses include `AuthenticationError`, `NotFoundError`, `ValidationError`,
and `CommandError`.
For a detached agent, keep the returned session id and follow its durable transcript:
with Tama() as tama:
machine = tama.get("worker")
session = machine.prompt(
"Run the tests, fix failures, and summarize the patch.",
agent="codex",
detach=True,
)
print(session.id)
for event in tama.logs(session.id):
print(event.data, end="")
Read-only RPCs retry short transient failures. Mutations never retry automatically: a
timed-out create, exec, or snapshot may already be running server-side. After an ambiguous
mutation failure, inspect `tama.list(all=True)` or `tama.get(name)` before trying again.
`Tama(timeout=...)` bounds ordinary control RPCs. Long operations such as stop, snapshot,
template creation and deletion have no artificial short deadline. `exec(...)` is also
unbounded by default; pass `exec(..., timeout=300)` when the command needs an explicit
client-side limit.
An attached prompt must receive a terminal log event or it raises `ProtocolError` rather
than inventing success. `detach=True` returns before an exit code exists, so combining it
with `check=True` is rejected.
## TypeScript SDK
Use the TypeScript SDK when Node.js or browser code should control Tama directly. It is
typed, promise-based, and the Node.js entry requires Node.js 20 or newer. Install it:
npm install @tama-computer/sdk@0.1.2
The package is `@tama-computer/sdk`. Browser bundles use
`@tama-computer/sdk/browser`. Complete TypeScript-only SDK guide:
https://tama.computer/typescript-sdk.txt
Node.js reuses the CLI profile selected by `tama login`. In CI, set `TAMA_TOKEN`.
`TAMA_API_URL` overrides the production gateway. Explicit constructor values take
precedence. Raw tokens and an optional `Bearer ` prefix are accepted:
import { Tama } from '@tama-computer/sdk'
const tama = new Tama({ apiKey: process.env.TAMA_TOKEN! })
console.log((await tama.identity()).account?.id)
Browser code supplies its current access token. An async provider is called for every
request, which lets a dashboard rotate credentials without recreating the client:
import { Tama } from '@tama-computer/sdk/browser'
const tama = new Tama({
apiUrl: 'https://gateway.tama.computer',
apiKey: async () => await auth.currentAccessToken(),
})
This is the safe shape for code that creates a billable machine. `check: true` makes a
non-zero remote exit raise `CommandError`. Stopping the machine is separate from the
lifetime of the local client:
import { Tama } from '@tama-computer/sdk'
const tama = new Tama()
const machine = await tama.new({ name: 'typescript-sdk-example', autoStopSeconds: 900 })
try {
const result = await machine.exec(
['python', '--version'],
{ check: true },
)
process.stdout.write(result.stdout)
} finally {
await machine.stop()
}
`machine.stop()` snapshots the machine and pauses billing. It is reversible with
`machine.start()`. `machine.delete()` and `tama.rm()` permanently destroy the
machine; never substitute either one for cleanup unless destruction was explicitly
requested. Letting a `Tama` object go out of scope does not stop remote resources.
The common object model mirrors Python:
await tama.new({ ... }) // create; waits until ready by default
await tama.list({ all: true }) // include stopped machines
const machine = await tama.get('worker')
await machine.exec(['pytest', '-q'], { check: true })
await machine.keepActive() // explicit idle-policy heartbeat
await machine.stop()
await machine.start()
await tama.snapshots.create(machine.id, { label: 'baseline' })
await tama.snapshots.fork(SNAPSHOT_ID, { name: 'attempt-2' })
await tama.templates.list()
await tama.secrets.list()
await tama.tokens.list()
await tama.files.list(machine.id, '/workspace')
Complete `Tama` surface:
await tama.identity() // account identity
await tama.usage(30) // balance and metered usage
await tama.offers() // available machine shapes
await tama.new({ autoStopSeconds: 900 }) // create; 15-minute idle auto-stop
await tama.list({ all: false }) // all:true includes stopped
await tama.get(nameOrId) // resolve one
await tama.keepActive(nameOrId) // refresh the idle deadline
await tama.rm(nameOrId) // PERMANENT delete
await tama.stop(nameOrId, { noSnapshot: false })
await tama.start(nameOrId, { wait: true, timeoutMs: 900_000 })
await tama.fork(snapshotId, { name: 'copy', wait: true })
await tama.exec(nameOrId, command, { cwd: '', check: false })
await tama.prompt(nameOrId, prompt, { agent: 'claude', check: false })
tama.logs(sessionId) // durable session transcript
tama.logs(machineId, pid) // low-level process logs
await tama.expose(nameOrId, port) // returns HTTPS URL
await tama.unexpose(nameOrId, port)
await tama.ports(nameOrId) // Map<port, URL | undefined>
await tama.desktop(nameOrId) // browser desktop URL
await tama.terminal(nameOrId) // browser terminal URL
await tama.enableSsh(nameOrId, publicKey)
A `Machine` has `id`, `name`, `status`, `statusDetail`, `autoStopSeconds`,
`lastActiveAt`, `autoStopAt`, raw protobuf `data`, and the latest stop restore point in
`snapshot`. Its actions are `refresh`, `keepActive`, `exec`, `prompt`, `stop`, `start`,
`delete`, `expose`, `unexpose`, `desktop`, `terminal`, and `enableSsh`.
Complete collection surface:
await tama.machines.create({ ... }) // also get/list/delete/stop/start
await tama.snapshots.create('worker', { label: 'baseline' })
await tama.snapshots.list({ machine: 'worker', automatic: false })
await tama.snapshots.fork(snapshotId, { name: 'copy' })
await tama.templates.create('worker', { name: 'base', public: false })
await tama.templates.list(); await tama.templates.delete(templateId)
await tama.secrets.set('OPENAI_API_KEY', value)
await tama.secrets.list(); await tama.secrets.delete('OPENAI_API_KEY')
const created = await tama.tokens.create('ci') // created.secret is returned ONCE
await tama.tokens.list(); await tama.tokens.revoke(created.id)
await tama.sessions.list('worker'); tama.sessions.logs(sessionId)
await tama.files.list('worker', '/workspace')
`startCreditPurchase(amountCents)` returns a checkout URL and
`confirmCreditPurchase(sessionId)` refreshes the balance after checkout. Send a human to
the console instead of automating payment. `tama.raw` is the generated Connect client for
forward compatibility; prefer the typed methods above.
For a detached agent, keep the session id and follow its durable transcript:
const machine = await tama.get('worker')
const session = await machine.prompt(
'Run the tests, fix failures, and summarize the patch.',
{ agent: 'codex', detach: true },
)
for await (const event of tama.logs(session.id)) {
process.stdout.write(event.data)
}
Read-only calls retry short transient failures. Mutations never retry automatically: a
timed-out create, exec, or snapshot may already be running server-side. After an ambiguous
failure, inspect `tama.list({ all: true })` or `tama.get(name)` before retrying.
`timeoutMs` on `new Tama(...)` bounds ordinary control calls. Long operations such as
stop, snapshot, template capture, deletion, and exec do not inherit that short deadline;
pass `exec(..., { timeoutMs: 300_000 })` for an explicit command limit. An attached
prompt must receive a terminal event or it raises `ProtocolError`; a detached prompt
cannot use `check: true` because its exit code does not exist yet.
## See what hardware there is
tama offers # aliased to `tama gpus`
tama offers --json
Columns are the card, its rate per hour, the fewest and the most of the card one machine
comes with, and the cores and memory the machine gets. Each row is the machine `new` would
give you for that card, at the price it is billed. A card with a serverless pool is one card
on shared capacity, priced per card-hour, with the size a spec naming it gets; `min gpus`
says `1`. A card without one is rented as a whole node, billed whole for as long as your
machine holds it, and the size is the whole box, since a rental is sized to the box that
turns up whatever `--cpu` and `--memory` said. A card only offered eight to a box is quoted
at the box, and `min gpus` says `8`. `--json` adds `cards_on_node`, `node_cpu_millicores`,
`node_memory_mb` and `starts_in`, which is `seconds` for a warm worker, `a minute` for a
pool with nothing up yet, and `minutes` for a rental that has to be provisioned.
## Take a machine
tama new # 1 vCPU, 1024 MiB, name generated for you
tama new trainer --gpu H100 # one card, sized for the node it is rented in
tama new api --port 3000 --port 8000 # published at create, URLs printed with it
tama new box --sync . # contents of the current directory into /workspace
tama new box --template h100-baseline # filesystem already in place
tama new box --json # the machine as JSON, for scripting
Every argument is optional. The flags worth knowing:
--gpu <CARD> a card by name; case does not matter
--gpu-count <N> leave at 1
--capacity <PATH> auto (default), serverless, or on-demand
--cpu <CORES> fractional allowed; 1 is the floor
--memory <MIB> MiB, not GiB; 1024 is the floor
--ttl <SECONDS> snapshot and stop after this many idle seconds; 0 disables it
--port <PORT> repeatable, published as the machine comes up
--env KEY=VALUE repeatable, non-secret
--secret <NAME> repeatable; a workspace secret, injected as that variable
--image <IMAGE> defaults to the machine base image
--dockerfile <FILE> build this and run it; --context sets the build context
--build-secret <NAME> a secret available only while the Dockerfile builds
--template <NAME> start from a template
--desktop include the virtual desktop; these machines resume cold
--no-ssh skip SSH setup
--sync <DIR> copy a local directory into /workspace on the way up
--json print the machine as JSON
Cards include B200, H200, H100, A100-80, RTXPro6000, L40S, RTX5090, A6000, RTX4090, and
others such as T4, L4, A10G, V100, GH200 and B300. `tama offers` is the list that is true
today.
1 vCPU and 1024 MiB are floors rather than defaults: the service takes the larger of what
you asked for and its own minimum. A machine that names a card is sized against the node
that card is rented in instead of that floor, so `--gpu H100` comes up with enough cores
and memory to keep the card fed. `--cpu` and `--memory` still win where you pass them.
Ports asked for at create are re-published on every restore and they follow a fork. A
machine has no idle timeout unless you ask for one (60 seconds minimum), so `--ttl` is
worth passing to anything you might forget about. Tama snapshots and uses the ordinary
stop path when the deadline expires. CLI/SDK calls, SSH/tunnels, agent sessions, and
published HTTP/WebSocket traffic refresh it. Background compute with no Tama-visible
traffic can look idle; disable the policy or call `keep_active()` / `keepActive()` from
its controller.
## Get code and data in and out
tama new box --sync . # at create
tama sync box .