Managing instances from the CLI

The Tinfoil CLI lets you manage projects and individual instances, along with model weights, secrets, SSH keys, registry credentials, and custom domains. This page walks through the full instance lifecycle from the terminal.

Prerequisites

Install or update to the latest published CLI by running the installer:

curl -fsSL https://github.com/tinfoilsh/tinfoil-cli/raw/main/install.sh | sh

Or download a binary from the releases page. A Docker image is published at ghcr.io/tinfoilsh/tinfoil-cli. Check your installation with tinfoil --version. You also need a Tinfoil organization with Tinfoil Containers enabled, the same prerequisite as the quickstart.

Updating the CLI

Check for a newer stable release or install it without logging in:

tinfoil update --check
tinfoil update

This updates only the CLI executable, not your running workloads, configuration, or keys. See Updating the CLI for JSON output, permissions, and package-manager guidance.

Authenticating

Container management requires an organization admin API key. A personal admin key selects a personal context and cannot manage organization instances. Create an organization key by following Getting a Tinfoil admin key, then run:

tinfoil login                        # prompts for the key (no shell history)
tinfoil login --api-key admin_xxx    # non-interactive, e.g. for CI
tinfoil whoami                       # confirm the effective credential and context
tinfoil logout                       # delete the saved credential

Credentials are written to ~/.tinfoil/config.json with mode 0600. whoami checks the effective credential with the server and displays its organization or personal context, user ID, controlplane URL, and credential source. For an organization context, it shows the returned organization ID; do not infer an organization from a key prefix or the GitHub repository owner. These environment variables can override saved configuration:

Variable	Purpose
`TINFOIL_ADMIN_KEY`	Highest-priority admin credential override
`TINFOIL_API_KEY`	Admin credential override only when its value starts with `admin_`; an inference key does not replace the saved admin login
`TINFOIL_TUNNEL_API_KEY`	Inference key (`tk_...`) for `tinfoil forward` and `tinfoil ssh`
`TINFOIL_CONTROLPLANE_URL`	Controlplane API base URL
`TINFOIL_CONFIG`	Alternate CLI configuration file path
`TINFOIL_NO_UPDATE_CHECK`	Set to `1` to disable passive update notices, not explicit `tinfoil update` or `tinfoil update --check`

Credential precedence is TINFOIL_ADMIN_KEY, then an admin key in TINFOIL_API_KEY, then the saved file. Logging in saves a key but does not unset environment overrides; logging out removes only the saved file. To switch organizations, clear or change active overrides, log in with the intended organization’s key, and check tinfoil whoami again.

Inspecting your organization

tinfoil project list          # repositories and aggregate instance counts
tinfoil project get myorg/my-app-config
tinfoil container list           # all instances in the org
tinfoil container get my-app     # full detail for one instance
tinfoil container hosts          # which container hosts your org may target

Pass -o json to get machine-readable output suitable for scripting:

tinfoil container list -o json | jq '.[] | select(.status == "failed")'
tinfoil container get my-app -o json

Projects can be referenced by repository name (owner/repo) or project UUID. Instances can be referenced by name or instance UUID. If a debug-mode and a production-mode instance share a name, the CLI lists both and asks for the UUID.

Publishing a config release

Before a tag can be deployed, the config repo must publish a measured release. In the dashboard, open the repository’s config editor under Containers, edit tinfoil-config.yml, open and merge the generated pull request, then follow the Release steps. Alternatively, commit the config change in GitHub and run the Tinfoil Release workflow from the repository’s Actions tab. Wait for both release workflow phases to finish before deploying the tag. See Updating for both workflows. The same flow is available from the CLI with tinfoil repo, which acts through the Tinfoil GitHub App installed on the repository:

# Read the current tinfoil-config.yml from the default branch
tinfoil repo config get myorg/my-app-config
tinfoil repo config get myorg/my-app-config --raw > tinfoil-config.yml

# Open a pull request with a locally edited config (use - to read from stdin)
tinfoil repo config pr myorg/my-app-config --file ./tinfoil-config.yml --body "Bump memory"
tinfoil repo pr status myorg/my-app-config 42

# Inspect release tags and trigger the Tinfoil Release workflow
tinfoil repo build info myorg/my-app-config
tinfoil repo build run myorg/my-app-config --version v0.0.1
tinfoil repo build status myorg/my-app-config --version v0.0.1

Merge the config PR on GitHub before repo build run; repo pr status must report Merged: true. repo build run only queues a release. repo build status checks its workflow without dispatching another run; also follow the GitHub Actions link and verify both tag creation and measurement/publication succeed. repo build info reports tags and published releases; confirm the same tag is published before creating the instance. It also suggests the next patch version. The build command accepts semver and adds the v prefix if missing. The repository must be public, so never put secret values in tinfoil-config.yml.

Creating an instance

Once v0.0.1 is measured and published, create an instance using that exact tag. For the template, create its GREETING_TOKEN secret first:

tinfoil container create my-app \
  --repo myorg/my-app-config \
  --tag v0.0.1

Flag	What it does
`--repo`	GitHub `owner/repo` containing `tinfoil-config.yml` (required)
`--tag`	Release tag to deploy (required)
`--variable KEY=VALUE`	Environment variable; repeatable
`--secret NAME`	Organization or repository secret to mount; repeatable
`--ssh-key NAME`	Org SSH key (debug instances only); repeatable
`--debug`	Deploy in debug mode
`--mark-latest=false`	Leave the repository’s latest GitHub release unchanged (defaults to `true`)
`--custom-domain`	Use a verified custom domain
`--host`	Pin to a specific host (see `tinfoil container hosts`)
`--volume ID_OR_NAME[:MOUNT_NAME]`	Beta. Attach an existing managed volume to a named mount and deploy; repeatable
`--replace ID`	Stop and remove an existing instance before queuing its replacement

The command follows the deployment, printing observed boot stages until the instance is Running, and exits non-zero if it observes a failure. Pass --no-wait or -o json to return the initial response without following progress. Create also records the project and revision you typed in your connection policy, so the first connect from this machine does not prompt. Before updating anything, send the first verified request, using the reported domain and myorg/[email protected]. Optional flags above are for applications that need them; a custom domain must already be verified, and selected secrets must already exist. A named volume mount requires a disk only when it declares key-secret (JSON key_secret). Pass --volume for each required mount; optional mounts may remain empty. If required mounts exist and you omit --volume, create refuses before creating the instance and prints the volume create and container create --volume commands to run. See Create and attach a volume. Initial creates cannot be held for review. Marking the tag as the repository’s latest GitHub release defaults to true; pass --mark-latest=false to leave it unchanged. It happens only when the GitHub App is connected, the repository is active, and an initial or changed tag is running on a non-debug instance. Explicit --host selection requires host-selection access for the organization, and the selected host and GPU size must be available to it. --replace is destructive: the old instance is stopped and removed before the replacement is queued. If the replacement later fails, the old instance is not restored.

Managing projects

One project contains all instances in your organization that use the same GitHub repository. Inspect its aggregate status and instance counts with:

tinfoil project list
tinfoil project get myorg/my-app-config

Set whether eligible project updates use hold for review by default:

tinfoil project settings myorg/my-app-config --hold-by-default=true

Individual container update operations, including config-only updates, and batch project update operations inherit this setting when --hold is omitted. An explicit value applies only to that operation; it does not change the project default. Creates and deploys are never held. Update all running instances to one release:

tinfoil project update myorg/my-app-config --tag v1.0.1

To update only selected instances, repeat --instance with each instance UUID:

tinfoil project update myorg/my-app-config \
  --tag v1.0.1 \
  --mark-latest=false \
  --instance 550e8400-e29b-41d4-a716-446655440000 \
  --instance 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Pass --hold=true or --hold=false to override the project’s default for one update. Use =: a space-separated boolean is parsed as another positional argument. Holding applies only to blue/green updates (CPU-only and single-GPU instances without persistent volumes). If preflight finds an eligible instance whose target release requires replacement, a held project update is rejected before any instance is updated. Only running instances are updated; stopped and failed instances are skipped (bring them up with container deploy), as are instances with an update already in progress. Without a hold, replacement updates require downtime confirmation; pass --yes in scripts. After preflight, results are reported per instance, and the command exits non-zero if any instance is skipped or fails. Marking the tag as the latest release defaults to true and happens for each changed tag once it is running and serving production, subject to the repository and GitHub App conditions described above. For held updates it happens after promotion. Pass --mark-latest=false to leave the latest release unchanged.

Lifecycle

An instance is either running or it is not. deploy boots an enclave for an instance that has none; update replaces the version a running instance serves. To run the same version on a fresh enclave, update a blue/green instance to its current tag (no downtime), or stop and then deploy any instance (downtime).

# Stop a running instance (saved settings and persistent volumes remain)
tinfoil container stop my-app

# Deploy a stopped or failed instance (optionally with config overrides)
tinfoil container deploy my-app
tinfoil container deploy my-app --tag v1.0.1
tinfoil container deploy my-app --volume dev-disk:workspace
tinfoil container deploy my-app --host gpu-host-2

# Update a running instance to a new tag or configuration
tinfoil container update my-app --tag v1.0.1
tinfoil container update my-app --tag v1.0.1 --hold=true
tinfoil container update my-app --tag v1.0.1 --mark-latest=false
tinfoil container update my-app --variable LOG_LEVEL=debug
tinfoil container update my-app --secret NEW_KEY --secret OTHER_KEY

# Delete (irreversible; prompts unless --yes)
tinfoil container delete my-app

deploy and update support --tag, --variable, --secret, --ssh-key, --debug, --mark-latest, and --custom-domain. deploy also supports --volume and --host; update also supports --hold. Supplied variables replace the full saved per-instance variable map; they do not replace the measured env values in tinfoil-config.yml. In managed delivery, a supplied secret list replaces the saved manual selection, then merges with declared secrets that exist in repository or organization scope. Supplied SSH-key lists replace their saved selections. --secret selects managed secrets, never private-keyserver names. A non-debug private target requires an empty managed selection; omitting --secret does not clear saved bindings. Pass a single --secret="" to send "secrets": [] on an individual create, deploy, or update; do not combine it with named selections. When switching to private delivery, also remove colliding saved variables with a complete replacement map. See the CLI and API transition example. Never upload private values as a workaround. In managed delivery, declared secrets are still merged after clearing the manual selection. A running instance cannot change hosts. Stop it, then deploy it with --host. Host access and GPU entitlement are validated when you select a host. A volume cannot automatically move to another host. When deploying after a stop, wait until the instance is Stopped before changing its tag, host, or disk attachments. A deploy queued while it is Stopping retains the current tag, host, and disk attachments. deploy --volume must attach the disk first, so it fails rather than queueing if the instance is still Stopping. deploy, update, and promote follow progress, printing observed boot stages and exiting non-zero if they observe a failure. A held update returns when the candidate is ready for review, without switching production traffic; other successful operations finish when the instance is Running and the update has completed. Pass --no-wait or -o json to return the initial response without following progress.

tinfoil container delete permanently removes the instance, its secret bindings, and its DNS records. There is no undo. Managed volumes are retained as unattached disks; delete them separately to erase their data.

Updates and downtime

Before submitting an update, the CLI prints a read-only current-to-target plan: tags, CPU/RAM/GPU resources, strategy and downtime, effective hold and its source, changed setting names, retained volume data, and whether to mark GitHub latest. No secret values are printed. The plan is not a historical snapshot or a reservation; the server validates the update again when it is submitted. When the plan includes secret_delivery, the CLI distinguishes managed and external secret names and states that private-keyserver authorization and unlock are not verified. JSON output preserves this optional object and its external_secrets_verified: false field; see the response schema. CPU-only and single-GPU instances without persistent volumes update blue/green: the new version boots alongside the current one and traffic switches once it is running. Multi-GPU instances and instances with persistent volumes cannot run two copies, so update stops the current version first and deploys the new one in its place. The CLI describes the downtime and asks you to type yes before proceeding; pass --yes in scripts. tinfoil container get shows Updates: replace for instances whose updates cause downtime.

tinfoil container get my-app       # shows the in-progress update and its stage
tinfoil container promote my-app    # switch traffic to a held update that is ready
tinfoil container cancel my-app    # discard the new version, keep the current one

When held for review, a blue/green update that is ready waits for container promote while the current enclave serves production. Otherwise traffic switches automatically. container cancel discards the new version without changing the production-serving instance; it also clears a failed update. Updates that replace the running instance cannot be held or canceled once the current version has stopped.

Volumes

Manage encrypted persistent volumes (Beta) with tinfoil volume:

tinfoil container hosts                                   # volumes live on one host
tinfoil volume create my-db-data --size 100GiB --host HOST_NAME
tinfoil volume list
tinfoil volume attach my-db-data my-db --as data          # instance must be stopped
tinfoil volume detach my-db-data                          # keeps the data
tinfoil volume rename my-db-data --name archive-data
tinfoil volume delete archive-data                        # erases the data; must be detached

Attach and detach require the instance to be stopped. Pass --volume to container create or container deploy to attach and deploy in one step.

Secrets

Manage organization secrets with tinfoil secret:

tinfoil secret list

# Create
tinfoil secret create DATABASE_URL --value-file ./db.url
echo -n "$STRIPE_KEY" | tinfoil secret create STRIPE_SECRET_KEY --value-file -

# Update value (instances using it are marked stale; update them to pick up the new value)
tinfoil secret set DATABASE_URL --value-file ./db.url

# Inspect (the value itself is never returned)
tinfoil secret get DATABASE_URL

# Delete (fails if any instance references it)
tinfoil secret delete DATABASE_URL

Secrets scoped to a single repository use tinfoil repo secret with the same subcommands and flags:

tinfoil repo secret list myorg/my-app-config
tinfoil repo secret create myorg/my-app-config DATABASE_URL --value-file ./db.url
tinfoil repo secret set myorg/my-app-config DATABASE_URL --value-file -
tinfoil repo secret get myorg/my-app-config DATABASE_URL
tinfoil repo secret delete myorg/my-app-config DATABASE_URL

Repository secrets are also available from the Project secrets section of the repository’s config editor under Containers in the dashboard. The same secret name can have different values in different repositories. An organization secret and a repository secret cannot share a name within the same organization. --value-file accepts - for stdin, which is the recommended way to set secrets because it keeps the value out of shell history and process listings. See secrets and env vars for the underlying model.

SSH keys

Debug-mode instances authorize SSH access using public keys registered at the org level: Choose one of the supported input forms:

tinfoil ssh-key list

# Read from a file
tinfoil ssh-key create laptop --public-key-file ~/.ssh/id_ed25519.pub

# Or read from stdin
cat ~/.ssh/id_ed25519.pub | tinfoil ssh-key create laptop --public-key-file -

# Or pass the public key inline
tinfoil ssh-key create laptop --public-key "ssh-ed25519 AAAA..."

tinfoil ssh-key delete laptop

Reference keys with --ssh-key NAME on tinfoil container create, deploy, or update.

Registry credentials

For private images, set credentials per registry. The CLI supports ghcr, gcr, and dockerhub; configure ECR and custom registries in the dashboard or through the Admin API.

tinfoil registry list

# GitHub Container Registry: classic PAT with read:packages
tinfoil registry set ghcr --username my-gh-user --token ghp_xxx

# Google Artifact Registry / Container Registry: service-account JSON
tinfoil registry set gcr --key-file ./gcp-sa.json

# Docker Hub: PAT with read permission
tinfoil registry set dockerhub --username my-docker-user --token dckr_xxx

# Remove credentials for a registry
tinfoil registry delete ghcr

Custom domains

tinfoil domain list

# Register a domain, then add its traffic and certificate CNAME records
tinfoil domain add api.example.com

# Re-check DNS after configuring records
tinfoil domain verify api.example.com

# Remove (fails if any instance uses it)
tinfoil domain delete api.example.com

Once a domain is verified, deploy an instance against it with tinfoil container create ... --custom-domain api.example.com. See custom domains for the DNS record details and troubleshooting.

Model weights

For GPU inference instances, tinfoil model prepares Hugging Face weights as verified artifacts that enclaves load with integrity checking. See Model weights for how the pieces fit together.

# Wrap a model on a host; --wait prints the tinfoil-config.yml block when done
tinfoil model wrap google/gemma-4-31B-it --host gpu-host-1 --wait

# Gated or private repos
tinfoil model wrap meta-llama/Llama-4-8B --host gpu-host-1 --hf-token-file ./hf.token

# Update a previously wrapped model to its latest (or a specific) revision
tinfoil model update google/gemma-4-31B-it --host gpu-host-1 --wait

# Inspect wrap jobs
tinfoil model list
tinfoil model status gpu-host-1 <job-id>   # add --logs for wrap logs

# Delete a wrap job (removes the artifact once nothing references it)
tinfoil model delete gpu-host-1 <job-id>

wrap pins the repo’s latest default-branch commit unless --commit is given. update requires an existing completed wrap of the repo on that host and resolves the newest commit when --commit is omitted; when an update run with --wait completes, it prints the new models: block along with the delete command for the previous wrap job. Run that delete only after the new config is released and deployed. delete is refused while a job is running or while any deployment on the host references the artifact.

Connecting to a deployed instance

Beta: Verified connections use V3 attestation, which is still being deployed. This designation applies to connection verification and V3-dependent features, rather than ordinary instance management.

tinfoil container connect <name> resolves the production connection’s domain and config reference, checks the resolved config against your local connection policy, then runs a verified local proxy pinned to that config. It saves you from looking up those values and passing them to tinfoil proxy -e <domain> -r <repo>@<tag> by hand:

# Interactive: the first connect shows the resolved config and asks you to
# confirm it (unless container create already seeded it); after that it's silent.
tinfoil container connect my-app -p 3301

# Scripts (no terminal) state their expectation instead of answering a prompt.
# The resolved config must fall under the reference, which is then remembered:
tinfoil container connect my-app -p 3301 --repo myorg/my-app-config          # any revision
tinfoil container connect my-app -p 3301 --repo myorg/[email protected]  # exactly this one

# Skip the policy check for one invocation; nothing is remembered:
tinfoil container connect my-app -p 3301 --dangerous

For a blue/green candidate, use tinfoil container connect my-app --review -p 3301. It pins the candidate tag and refuses if no review connection is available; it never falls back to production. container get and deployment progress output print available URLs with verified HTTP request commands. See Hold for review. The proxy binds to 127.0.0.1 by default. Pass --bind <ADDRESS> to use another interface:

tinfoil container connect my-app --port 3301 --bind 0.0.0.0

Only bind beyond localhost on a trusted network because other hosts may then send requests through the proxy. In another terminal, send requests to http://localhost:3301 exactly as you would to your instance’s domain. The proxy verifies attestation on startup and pins the TLS certificate for subsequent requests. See connecting for the full client story (SDKs, raw tinfoil http).

Debug-mode instances do not pass attestation, so connect (and any other SecureClient flow) will refuse to use them. SSH into debug instances directly via ssh -p <port> [email protected]. The dashboard shows the exact command on the instance’s card.

Connection policy

Inspect or configure the policy that gates these connections with the trust command — the file is ~/.tinfoil/known-configs.yml, yours to edit, and the CLI preserves your comments when it writes:

tinfoil trust                             # show mode, record, and the allow list
tinfoil trust set --mode frozen           # unknown configs fail instead of prompting
tinfoil trust set --record pin --prune    # record exact pins; remove broader entries

See the connection policy reference for the file format, matching rules, and script guidance.

Resource metrics

tinfoil container metrics my-app --time 24h

Returns a JSON object with data_points and interval. Each data point has a timestamp, average and maximum CPU/GPU utilization, average and maximum CPU/GPU memory utilization, and CPU/GPU total memory. interval is the width of each time bucket. This is useful for piping into jq or a chart tool.

Scripting tips

-o json is supported on every list/get command.
Exit codes are non-zero on failure, with the API error message printed to stderr.
All commands respect the environment overrides listed above, so the CLI is safe to use from CI. Store the admin key as a secret and pass it through the environment instead of running tinfoil login.
--verbose and --trace increase log verbosity for debugging connectivity issues.

Getting Started

Model catalog

Tinfoil SDKs

Tinfoil Chat

Local Proxy

Tinfoil Containers

Guides

Verification & Attestation

Tutorials

Admin API

Resources

Prerequisites

Updating the CLI

Authenticating

Inspecting your organization

Publishing a config release

Creating an instance

Managing projects

Lifecycle

Updates and downtime

Volumes

Secrets

SSH keys

Registry credentials

Custom domains

Model weights

Connecting to a deployed instance

Connection policy

Resource metrics

Scripting tips

​Prerequisites

​Updating the CLI

​Authenticating

​Inspecting your organization

​Publishing a config release

​Creating an instance

​Managing projects

​Lifecycle

​Updates and downtime

​Volumes

​Secrets

​SSH keys

​Registry credentials

​Custom domains

​Model weights

​Connecting to a deployed instance

​Connection policy

​Resource metrics

​Scripting tips

Prerequisites

Updating the CLI

Authenticating

Inspecting your organization

Publishing a config release

Creating an instance

Managing projects

Lifecycle

Updates and downtime

Volumes

Secrets

SSH keys

Registry credentials

Custom domains

Model weights

Connecting to a deployed instance

Connection policy

Resource metrics

Scripting tips