silicon-cli 1.0.20

Silicon CLI — create, run, and manage your silicon instances.

silicon-cli

This is the single source for the installable silicon command. The PyPI package is named silicon-cli, and the code lives here in this silicon-cli repo.

The command manages silicon instances on a machine: create them from the silicon-stemcell base, start/stop them under an auto-restart watchdog, stream logs, and back them up to Glass. It reads the same ~/.silicon/registry.json, so existing installs carry over unchanged.

Install

pip install --upgrade silicon-cli

The package has a small runtime dependency footprint and installs the complete silicon team-management command.

Commands

silicon                      Show status or list instances
silicon new [dir]            Create a new Silicon (hydrate from stemcell)
silicon new .                Hydrate the current folder into a runnable silicon
silicon start <target>       Start silicon(s). target = name, *, all, 1,2,4, or name,name
silicon stop [--full] <target>  Stop silicon(s). target = name, *, all, 1,2,4, or name,name
silicon restart <target>     Restart silicon(s). target = name, *, all, 1,2,4, or name,name
silicon agent <start|stop|status> [name]   Manage the per-silicon glass agent
silicon status [name]        Show instance status
silicon browser [name]       Open a headed browser for login
silicon browser-profile setup          Create a cloud browser profile through Glass
silicon browser-profile finish <session_id>  Finish profile setup
silicon debug [name]         Tail a running instance's logs
silicon attach [path]        Register an existing silicon directory
silicon pull [api_token]     Pull a Glass team or silicon into local folders
silicon push [name] [now|stop|status]   Daily 23:59 GMT backups to Glass
silicon backup [name] [now|stop|status] Alias for silicon push
silicon update <target>      Task-safely update silicon(s) from the latest stemcell
silicon update --dry-run <target>  Verify and show the exact update/merge plan
silicon update status [name]       Show active generation and transaction state
silicon update cancel [name]       Cancel before the service-stop boundary
silicon update resume [name]       Recover an interrupted transaction
silicon update history [name]      Show durable transaction history
silicon update rollback [name]     Task-safely reactivate the prior generation
silicon list                 List all instances
silicon docker init [--root ~/silicons] [--image registry/repository@sha256:<digest>]
                             Check Docker and enable one-container-per-Silicon runtime
silicon docker doctor        Check/repair Docker runtime setup
silicon docker login [claude|codex|all]
                             Set up shared Claude/Codex auth for Docker silicons
silicon docker compose       Print generated Compose file path
silicon claude [args...]     Run Claude Code with shared Docker auth
silicon codex [args...]      Run Codex with shared Docker auth
silicon script update        Update this CLI itself
silicon package inventory --json
                             Report host, Docker, and per-instance package versions
silicon package update <package> [--silicon-id ID]
                             Safely update every selected copy of one package
silicon help                 Show help

silicon package update accepts silicon, silicon-cli, silicon-browser, silicon-extend, silicon-interface, claude, or codex. Shared pip/npm copies update once on the host. Local instance copies update only across a safe stop boundary, and Docker copies move through the signed runtime release instead of being modified inside a running container. Glass uses the JSON form of these commands to provide team-scoped inventory and durable update jobs.

Configuration (env vars)

Var	Default	Purpose
SILICON_HOME	~/.silicon	registry + CLI state
GLASS_SERVER_URL	https://glass.teamofsilicons.com	Glass sync server (pull/push)
SILICON_RELEASE_MANIFEST_URL	<GLASS_SERVER_URL>/api/v1/silicon-release/latest.json	signed schema-1 release manifest
SILICON_RELEASE_TRUSTED_KEYS	packaged production keys	JSON map of key id to base64 raw Ed25519 public key; additive for self-hosting/key rotation
SILICON_UPDATE_ALLOW_UNSIGNED_GIT	(empty)	explicit compatibility opt-in; select exact-revision Git instead of the signed channel
SILICON_STEMCELL_REPO	teamofsilicons/silicon-stemcell	base for new
SILICON_PYTHON	python3	interpreter used to run a silicon's main.py
SILICON_INTERFACE_CLI_PACKAGE	@teamofsilicons/silicon-interface-cli	npm package used to install the Silicon Interface CLI
SILICON_INTERFACE_CLI_TARBALL	versioned npm tarball	fallback package URL if registry metadata is briefly unavailable
SILICON_INTERFACE_CLI_SOURCE	(empty)	local package dir or silicon-interface.mjs path for dev installs
SILICON_INTERFACE_CLI_SKIP	(empty)	set to 1 to skip interface CLI setup
SILICON_INTERFACE_DAEMON_SKIP	(empty)	set to 1 to install the CLI without starting its listener daemon
SILICON_RUNTIME	(empty)	default pull uses Docker; set to local to opt out
SILICON_RUNTIME_IMAGE	signed release manifest	bootstrap-only exact digest when no runtime digest is persisted; it cannot retarget an installed release
SILICON_DOCKER_ROOT	~/silicons	Docker-backed instance root
SILICON_DOCKER_COMPOSE	<root>/compose.yml	generated Compose file path
SILICON_DOCKER_SHARED_HOME	<root>/.shared-home	VM-wide Claude/Codex auth home mounted into every container
SILICON_DOCKER_SUDO	(empty)	set to 1 to run Docker commands through sudo docker
SILICON_DOCKER_ALLOW_UNPINNED_IMAGE	(empty)	unsafe local-development-only escape hatch; production must leave this unset
SILICON_UPDATE_RETAIN_GENERATIONS	3	bounded number of immutable update generations to retain (minimum safety floor: 2)

Docker runtime

Docker mode keeps the existing silicon command but runs each Silicon in its own container. Mutable instance state lives on the host under ~/silicons/<name> and is bind-mounted at /silicon inside the container. Provider secrets are still Glass-managed: the container stores only the Silicon's .glass.json key and the stemcell fetches provider keys from Glass on boot.

Claude Code and Codex account state is shared across all Docker-backed silicons on the VM. The shared auth home defaults to ~/silicons/.shared-home and is mounted into every container. During an interactive silicon pull, the CLI asks whether to set up Claude Code, Codex, or both before installing the team.

On a fresh server, install Docker Engine and Compose v2 from the operating system's trusted package repository, verifying the vendor repository key as documented by Docker. The CLI never downloads or executes get.docker.com (or any other mutable installer) as root.

silicon pull first checks Docker and Compose without selecting an image. It then verifies the signed Silicon release manifest, reads the exact registry/repository@sha256:<digest> runtime identity covered by that signature, pulls it, and verifies Docker reports that same repository digest before any instance or credential is created. The digest is persisted on each instance and generation; updates switch it only at activation, and rollback restores the prior generation's digest. A cached image is reusable only when that exact digest verifies. Pull completes only after each active Docker Silicon exposes the pinned Silicon Extend package and its silicon-extend command.

pip install silicon-cli
silicon pull sct_live_...

To run the same checks explicitly:

silicon docker bootstrap --root ~/silicons
silicon docker doctor

To set up or repair shared Claude/Codex login manually:

silicon docker login        # asks which accounts to set up
silicon docker login claude # Claude Code only
silicon docker login codex  # Codex only
silicon docker login all    # both

Codex login uses codex login --device-auth inside the runtime container so it works on remote/headless servers without browser port forwarding.

To use those same shared accounts directly from the VM without installing Claude or Codex on the host:

silicon claude
silicon codex
silicon claude --version
silicon codex --version

The runtime image contains the complete Silicon runtime contract: Silicon CLI, Silicon Browser, Silicon Extend, Silicon Interface CLI, Claude Code, Codex, Node 22+, Python tooling, and Git. silicon pull verifies every command, minimum supported version, and the Python dependency graph in the exact signed image digest before it asks Glass to claim or register a Silicon. Immutable releases use the updater's pre-staged, hash-locked dependency environment. Only a legacy flat installation falls back to creating /silicon/.venv from its requirements.txt, so per-Silicon Python dependencies do not pollute the host.

To force the older host-local install path:

SILICON_RUNTIME=local silicon pull sct_live_...

Local mode deliberately bypasses the bundled image, so the pull verifies Node 22+, npm, Python, Git, Silicon Browser, Silicon Extend, and the selected Claude/Codex CLI on the host. It installs and verifies the per-Silicon Interface CLI while the pull is still staged; a missing prerequisite aborts the pending Glass claim with an actionable update command.

After that, the normal commands continue to work:

silicon list
silicon start all
silicon stop ada          # stops the Silicon process; container stays up
silicon stop --full ada   # stops the container
silicon debug ada
silicon update ada
silicon backup ada now

The generated Compose file is written to ~/silicons/compose.yml. You can inspect it with:

silicon docker compose

Build and publish the runtime image from this repo, then record the registry's immutable digest in Glass as SILICON_RELEASE_RUNTIME_IMAGE before publishing the matching Stemcell release:

docker build -f docker/runtime/Dockerfile -t ghcr.io/teamofsilicons/silicon-runtime:<version> .
docker push ghcr.io/teamofsilicons/silicon-runtime:<version>
docker image inspect --format '{{json .RepoDigests}}' ghcr.io/teamofsilicons/silicon-runtime:<version>

For local CLI, Silicon Browser, and Silicon Extend development, build their wheels into separate directories and layer them over the published runtime without publishing first:

python -m pip wheel . --no-deps --wheel-dir /tmp/silicon-cli-wheel
(cd ../silicon-browser && uv build --wheel --out-dir /tmp/silicon-browser-wheel)
(cd ../silicon-extend && uv build --wheel --out-dir /tmp/silicon-extend-wheel)
docker build \
  --build-arg BASE_IMAGE=ghcr.io/teamofsilicons/silicon-runtime@sha256:<digest> \
  --build-context silicon_cli_wheel=/tmp/silicon-cli-wheel \
  --build-context silicon_browser_wheel=/tmp/silicon-browser-wheel \
  --build-context silicon_extend_wheel=/tmp/silicon-extend-wheel \
  -f docker/runtime/Dockerfile.local \
  -t silicon-runtime:v2-local .

Silicon Interface CLI

For Docker-backed installs, the Silicon Interface CLI is installed inside the runtime image/container. For host-local installs, silicon new, silicon install, and silicon pull set up the Silicon Interface CLI in the silicon folder when Node 22+ is available. When a Glass .glass.json is present, setup also starts the background listener daemon so the silicon receives live conversation frames without polling.

silicon pull is token-native. Generate a team setup token from Glass > Silicons > Team setup token, then run:

silicon pull
# paste the token when prompted

# or, less private because it lands in shell history:
silicon pull sct_live_...

The command validates the token with Glass and opens one idempotent, time-bounded credential claim for the entire team. An ambiguous retry replays that same encrypted claim instead of minting duplicate valid Silicon keys. Every target name is preflighted first; hydration then happens in hidden owner-only staging directories. Only after every generation and secret-file permission verifies does the CLI atomically rename the stages into place, commit the Glass claim, register the exact identities, regenerate Compose for Docker-backed installs, and start each Silicon.

Pull progress is journaled without credentials under ~/.silicon/pull-transactions/ using owner-only files. A crash before commit resumes the same hidden stages and release identity. A normal pre-commit failure removes only transaction-marked stages and asks Glass to revoke the abandoned claim keys. A crash after a rename resumes registration/start without creating duplicate registry, service, or container identities.

During team pull, setup asks for the default brain/fallback settings once. You can apply those settings to every silicon, or select specific silicons that need different settings and answer the brain prompt for those silicons only. Older per-silicon scs_live_... tokens still pull just that one silicon.

Provider API keys for voice, browser profiles, billing, and architecture generation are configured on the Glass backend. After the silicon API token is validated, silicon pull reads the team's provider-key metadata from Glass and automatically marks the pulled silicon(s) to use Glass-managed keys when every provider is available. Plaintext secrets are never returned to the CLI. A Glass-pulled silicon only stores its Glass API token plus a local marker that provider keys come from Glass.

The local wrappers are written to:

<silicon>/.silicon-interface/bin/si
<silicon>/.silicon-interface/bin/silicon-interface
<silicon>/.silicon-interface/inbox.jsonl
<silicon>/.silicon-interface/state.json

For Glass-pulled silicons, those wrappers automatically use the folder's .glass.json (server_url + api_key) for conversation API auth.

During local development, point SILICON_INTERFACE_CLI_SOURCE at the package:

SILICON_INTERFACE_CLI_SOURCE=../silicon-interface/packages/silicon-interface-cli silicon new ./ada

Backups

silicon push <name> now and silicon backup <name> now use the active immutable Stemcell generation's canonical backup implementation. First, the host CLI captures all current source and DNA customizations against the exact cached upstream release into .silicon/overlays, and records a verified latest.json reference that is included in the protected-data snapshot. The Stemcell then snapshots its mandatory policy plus any additive .backupsilicon paths and uploads the verified snapshot to Glass. Instances that predate the canonical backup module must first be stopped and updated with silicon update <name>; the CLI does not install or fall back to a second backup implementation.

silicon push <name> starts the background loop. Scheduled manifest backups run daily at 23:59 GMT and retry transient failures with bounded backoff. The host-owned supervisor also covers Docker instances, maintains a durable heartbeat, and refuses duplicate loops. Its enabled/disabled intent survives a host reboot; normal Silicon startup and every regular CLI startup reconcile a missing supervisor, while silicon backup <name> stop persists an explicit opt-out. Use silicon backup <name> status to inspect it; now remains available for one-shot manual backups.

Transactional updates

silicon update <name> stages and validates a complete immutable generation while the current Silicon keeps working. It then asks the running Stemcell to enter maintenance and waits until active work reaches a safe boundary. New Carbon messages remain durably accepted by Glass during this window; the sender sees that the Silicon is updating and that the message is queued, without needing to resend it.

Before stopping anything, the updater verifies a canonical recovery snapshot. It records the exact services that were running, atomically switches the active generation, restores that service state, and requires stable health checks before committing. A failure after the stop boundary automatically reactivates an authenticated reconstruction of the prior generation rather than trusting a writable dormant directory. The mutable data root, memory, credentials, conversations, and local customization overlay are kept outside immutable release generations.

Updates are journaled and crash-resumable. A second update cannot overlap an unfinished transaction:

silicon update --dry-run ada
silicon update --deadline 30m ada
silicon update status ada
silicon update cancel ada
silicon update resume ada
silicon update history ada
silicon update rollback ada

Cancellation is accepted only before the service-stop boundary. resume finishes or safely recovers an interrupted update according to its fsynced journal; it never guesses from a partially copied directory. Retention keeps the active, prior-known-good, and every nonterminal transaction generation even when old unreferenced generations are pruned. A durable highest-accepted signed release sequence remains in force even after an explicit runtime rollback.

The default release channel accepts only an expiry-checked HTTPS manifest with at least one valid Ed25519 signature from a pinned public key. The manifest pins the exact content-addressed artifact and every extracted file; candidate code is never executed to perform or validate the update. Key rotation is additive: ship a new key_id and raw 32-byte public key in the CLI keyring before Glass begins signing with it, retain the old public key through the supported-client window, then remove it in a later CLI release. A self-hosted public-only keyring uses this operator-ready format:

export SILICON_RELEASE_TRUSTED_KEYS='{"release-2026-01":"<base64 of the raw 32-byte Ed25519 public key>"}'

The matching private key belongs only in Glass's secret store as SILICON_RELEASE_SIGNING_PRIVATE_KEY; it must never be placed in this CLI, an instance directory, or the JSON above. Until the production key is securely provisioned and its public half is packaged, signed updates fail closed.

Production release-key handoff is deliberately explicit:

1. Generate the Ed25519 keypair offline or in an HSM.
2. Put only the standard-base64 raw 32-byte public key, under a stable key ID, in silicon_cli/release_trust_anchors.json.
3. Run python -m silicon_cli.updater.signatures --check-packaged; a clean source tree intentionally fails this gate until a real production anchor exists.
4. Build and publish the wheel, then configure Glass's release signer with the matching private key from its secret store/HSM.
5. For rotation, ship and deploy the new public anchor before Glass uses it, and retain the previous anchor until every supported CLI has crossed the overlap window.

For a deliberate compatibility operation, --allow-unsigned-git (or SILICON_UPDATE_ALLOW_UNSIGNED_GIT=1) selects the exact-revision Git source. It is never an automatic downgrade. That mode pins a single commit and verifies the downloaded tree and archive by SHA-256, but it cannot authenticate the publisher and always emits a warning.

Implementation notes

• The PyPI package provides the silicon console entry point.
• The auto-restart watchdog runs as silicon _watchdog (a detached supervisor process) with crash-loop detection and .silicon.stop, .silicon.pid, and .silicon.log state.
• silicon script update runs python -m pip install --upgrade silicon-cli with the interpreter that owns the current command.
• Everything (server, stemcell repo) is env-overridable.