One home for
your silicons.

What runs on your machine

Silicon is a local interpreter for a silicon.yaml file. One interpreter can connect several Silicons. Each Silicon has its own identity, home directory, internal Silicons (ISIs), access rules, event flow, sessions, and logs.

The silicon command manages the interpreter from your terminal. The si command is provided inside an ISI so it can communicate with permitted ISIs, inspect work, manage its session, and ask the interpreter to authenticate an application. The local dashboard exposes the same management operations through the interpreter's control API.

The interpreter listens on 127.0.0.1:1823. If that port is occupied, it tries 1822, 1821, and so on, down through 1024. A dedicated Caddy process provides http://silicon.localhost for the dashboard and http://<local-id>.<org-id>.localhost for each connected Silicon. Caddy uses HTTP port 80; it does not search for an alternative proxy port.

Each active ISI session has an owned Omni daemon and uses Silicon Omni's Rust package. Omni starts and communicates with the selected inference provider. Silicon subscribes to Omni events, delivers new messages, assembles DNA, tracks sessions, and records progress. These are real provider processes; the interpreter does not simulate model output in normal use.

No terminal window is opened for each ISI. Each receives an independent process context, an Omni session, and the environment needed by its commands. Persistent session data survives stopping the interpreter. Global ephemeral work is discarded when it finishes.

Installation

Public binary installation

The public installer is designed to download a complete, versioned bundle. It does not require a Rust compiler. Once the v3.5.0 release and its assets have been published and verified, the release-specific command is:

curl -fsSL https://github.com/teamofsilicons/silicon-stemcell/releases/download/v3.5.0/install.sh | sh

At this documentation snapshot, publication is pending. An unavailable bundle is a hard installation error; the installer does not substitute an older Stemcell release.

The default installation prefix is ~/.local/share/silicon. Add its bin directory to your shell's PATH:

export PATH="$HOME/.local/share/silicon/bin:$PATH"

For the default prefix, the installer adds this path once to the startup file for your detected shell. Open a new terminal, or run the printed export command in your current terminal. Set SILICON_NO_PATH=1 to leave shell startup files alone. Custom prefixes print the path without changing startup files.

To choose another dedicated prefix, set the variable on the sh side of the pipeline:

curl -fsSL https://github.com/teamofsilicons/silicon-stemcell/releases/download/v3.5.0/install.sh \
  | SILICON_PREFIX="$HOME/tools/silicon" sh

The target matrix covers macOS and Linux on ARM64 and x86-64. Windows is not a supported target. Release CI is configured to build each target; a local test on one architecture does not verify the other three.

The binary installation needs curl, tar, and a SHA-256 verifier (sha256sum or shasum). Downloads use HTTPS. Before activation, the installer checks the bundle checksum, required members, version marker, and whether the interpreter and Omni daemon can execute. A complete release includes:

The Commit and Remind wrappers suppress their independent update checks. Their underlying binaries are shipped as commit-native and remind-native inside the release. For a fresh Commit home with no explicit backend override or existing saved configuration, the wrapper selects https://backend.commit.teamofsilicons.com. It preserves an existing configuration or explicit COMMIT_API_URL.

The bundle supplies the listed client tools and local daemons. Accounts, permissions, remote service availability, and authenticated inference providers still have to be available. Installing a CLI does not create an IAM identity or grant provider access.

Linux and port 80

On Linux, the installer checks whether unprivileged processes can bind port 80. If not, it grants only the bundled Caddy binary cap_net_bind_service=ep using setcap. This requires the system's libcap tools and suitable privileges; it can ask for sudo in an interactive terminal. Silicon itself does not need to run as root.

An automatic, noninteractive update cannot prompt for privileges. When the Caddy binary is unchanged, the installer can reuse the existing capability. If a new Caddy binary needs a capability and unattended privilege is unavailable, activation fails with an explanation and leaves the current release selected. Rerun the installation or update interactively.

Build the complete installation from source

From this repository's root:

SILICON_SOURCE_DIR="$PWD" sh install.sh

Source installation requires Rust 1.98 or newer, Cargo, a C compiler, and dependencies needed by the pinned Rust crates. Release CI pins Rust 1.98.1. It builds the interpreter and every required application, and downloads verified Caddy. Caddy's upstream checksum file uses SHA-512.

SILICON_GIT_REV is an alternative to SILICON_SOURCE_DIR: supply an exact, lowercase, 40-character Git commit. The installer fetches that commit and verifies the checkout. The two source selectors cannot be used together.

For controlled builds, SILICON_DEPENDENCY_BIN_DIR can supply already-built, trusted dependency executables. This is a reuse mechanism, not independent verification of arbitrary local binaries. The interpreter is still built from the selected source. CARGO_TARGET_DIR can reuse a compilation directory.

For a developer build of only the interpreter and internal CLI:

cargo build --locked
./target/debug/silicon --help
./target/debug/si --help

This does not install the required runtime dependencies. Put the intended omnid, Caddy, IAM, and application commands on PATH, or use the documented binary overrides. Automatic bundle updates do not replace an unmanaged target/debug or target/release executable.

Activation and retained releases

Installed commands are symlinks through <prefix>/lib/silicon/current/bin. A new release is prepared under the same prefix, checked, moved into <prefix>/lib/silicon/releases, and selected by replacing the current symlink. Existing unmanaged files in <prefix>/bin are not overwritten; choose another prefix if there is a conflict.

Only one installation may modify a prefix at a time. A stale .install-lock after a forced kill requires checking that no installer is running before removing the lock. Old release directories are retained; there is no automatic release-pruning or public rollback command in this version.

The installer does not copy the repository's stemcell examples into a user's home. It never edits a connected silicon.yaml, memories, workspace, or session archive.

First Silicon

Create your own directory and your own silicon.yaml. Keep it separate from the repository's reference fixture. The following is a complete schema example. Replace the identity and token with your values and ensure Omni has an authenticated provider that can satisfy the fast model key.

silicon:
  id: assistant:my-org
  token: REPLACE_WITH_YOUR_SILICON_TOKEN
  timezone: Asia/Kolkata
  SILICON_HOME: ! pwd
  inference_providers:
    - all-available-providers

isi:
  assistant:
    model: fast
    primary_send_mode: global
    session_type: persistent
    dna:
      assemble:
        - '! printf "You are a helpful assistant. Keep useful notes in your workspace."'
      next_refresh: 30min

access:
  assistant: []

flow:
  - send:
      isi: assistant
      message: '{request.data.message}'

No application login is configured in this example. Add application commands when the corresponding Silicon identity and application permissions are ready. token remains required even if the first test does not use an IAM application.

silicon compile /absolute/path/to/silicon.yaml
silicon connect /absolute/path/to/silicon.yaml
silicon ls
silicon send assistant:my-org assistant "Hello"
silicon show assistant:my-org assistant
silicon web

compile validates configuration and expressions without connecting to the interpreter. It does execute compile-time Bash expressions, including SILICON_HOME, so it is not a side-effect-free shell dry run. All expression syntax is checked before those commands execute. Provider startup, application authentication, and runtime request values have their own checks later.

connect starts the interpreter if necessary, compiles the file, checks managed application authentication, adds routing, registers configured webhooks, and records the connection. Duplicate Silicon IDs, duplicate canonical YAML paths, or two connected Silicons sharing the same canonical SILICON_HOME are rejected.

The local identity is the canonical YAML path. The global identity is silicon.id. Moving a file changes its local identity. Editing a connected file does not live-reload it. Disconnect and reconnect to apply changes; restart restoration also recompiles the saved path. The interpreter never rewrites the file for you.

Send an event through the Silicon's host:

curl --fail-with-body \
  --header 'Content-Type: application/json' \
  --data '{"type":"new_message","data":{"message":"Hello from an event"},"metadata":{}}' \
  http://assistant.my-org.localhost/events

Caddy routes the hostname but does not edit DNS or /etc/hosts. If a particular client does not resolve .localhost names, the equivalent diagnostic command can add --resolve assistant.my-org.localhost:80:127.0.0.1.

Configuration reference

The four required top-level keys are silicon, isi, access, and flow. Unknown fields are errors. Ordinary duplicate YAML keys are errors. Flow action order is preserved, including the reference dialect's repeated if keys, but the recommended form is an explicit list of steps.

silicon

SILICON_HOME: ! pwd runs pwd with the YAML's parent directory as its working directory. Once home is resolved, later compile-time commands and runtime scripts use that home. Compile-time fields are evaluated once per compilation, not on every incoming event.

Provider selection walks the list from top to bottom. all-available-providers adds Omni's available providers, except NAME removes a provider, and a later explicit name adds it back. Nested lists follow the same order:

inference_providers:
  - all-available-providers
  - except codex-app-server
  - [claude-code-cli]

A single all-available-providers entry uses Omni's native selection. Explicit names are checked against Omni's installed/authenticated providers when a session initializes. An empty final selection is an error. This version does not implement extra named groups such as open-weight-models unless Omni exposes that exact name as a provider.

login and webhook contain executable names and arguments, not shell programs to run while compiling:

login:
  - ! dm
  - 'hook --profile work'
webhook:
  - ! dm
  - 'hook --profile work'

These fields expand CEL and !>> fallbacks, preserve argument quotes, and remove an original leading ! as a legacy app-command marker. They do not execute Bash during evaluation. For example, ! dm identifies the app to which Silicon later appends iam --json, a login command, or a webhook command; it does not launch bare dm during compilation. Command arguments are parsed with shell-style quoting and executed directly as argv. Shell pipelines, redirections, and environment assignments are not command wrappers; use a real executable wrapper when one is required.

isi

Define at least one ISI. Names may contain ASCII letters, digits, ., _, and -, up to 128 bytes; . and .. alone are not allowed.

Legacy fields are accepted with warnings:

Conflicting legacy and canonical settings are rejected. In particular, archive_on_end: false does not mean ephemeral. Use canonical names in new configurations.

Intervals and scheduled work

Bare numeric intervals are minutes. 30min, 30m, 10s, and 2h are also accepted. Values must be finite and positive, at most ten years. Timing expressions can use Bash, CEL, and fallbacks; the evaluated result must satisfy the same interval rules.

DNA is assembled at session initialization. next_refresh is reevaluated after assembly and after each refresh. Refresh work runs separately from the provider event listener, so a slow DNA command does not block receipt processing. A failed refresh is logged and retried after approximately 60 seconds.

Heartbeat next is evaluated when its schedule is created and when it becomes due. The first heartbeat waits for its configured interval. A global ISI can be started by its heartbeat. A session-addressed ISI gets independent heartbeat schedules for existing active session addresses; a heartbeat does not invent a missing session ID. App authentication is checked before delivery. Failed timing evaluations are logged and retried after approximately 60 seconds.

Timers are best effort and have scheduler granularity; they are not wall-clock cron jobs. Keep interval expressions quick and deterministic enough for the desired schedule. DNA, heartbeat, and suggestion expressions inside a session-addressed ISI receive ISI=name:session-id.

A new-session suggestion is a message, not an automatic archive. It is considered after a normal incoming message. At least min_new_messages new messages since the last suggestion are required, and subsequent suggestions must respect cooldown_minutes. Heartbeats and suggestion messages do not count toward that threshold. The first suggestion can occur as soon as the message threshold is reached; the cooldown is between suggestions. Counters belong to each session. Archived sessions do not receive these suggestions.

DNA assembly

Each dna.assemble entry is one of:

• A path relative to SILICON_HOME, whose contents are read.
• A ! Bash expression whose stdout becomes prompt text.
• A fallback chain combining files, commands, and explicitly quoted literal text.

dna:
  assemble:
    - silicon.md
    - ! cat worker.md
    - ! ./contacts.sh !>> CONTACTS.md !>> "No contacts are available."
  next_refresh: 30min

learn.sh without ! is a file to read. ! ./learn.sh executes it. Quoted fallback text inside the scalar is literal prompt content; ordinary YAML quotes around a path are only YAML syntax.

An exhausted DNA fallback is logged and that assembly entry is skipped. Other entries continue. The interpreter appends a small instruction footer identifying the current ISI, its home, allowed ISI targets and their addressing modes, and the relevant si --help entry points. Names outside that ISI's access list are not included in this footer.

access

Every ISI must have an access entry, including an empty one. Entries name ISIs in the same Silicon. Unknown names and duplicate targets are rejected.

access:
  coordinator: [researcher, worker.terminal]
  researcher: [coordinator]
  worker.terminal: [coordinator]

The server enforces these rules for internal sends and for inspecting or ending another ISI's sessions. An ISI may inspect itself and query its own archived sessions. Other sends to itself require an explicit self entry in its access list. The public management CLI and the trusted event flow act with interpreter authority.

These rules govern the si interface. They are not operating-system isolation between arbitrary programs running as the same user.

Expressions, JSON, Bash, and fallbacks

Strings support CEL interpolation in unescaped {...}. Evaluation proceeds from CEL to Bash, where the source explicitly starts with !, and finally to the resulting string. A string received from a request that happens to begin with ! is data; interpolation alone does not turn it into an implicit Bash command.

The runtime CEL environment contains:

Compile-time expressions do not have a live request; request and var start empty. Required configuration fields cannot depend on an event that has not arrived. Runtime DNA and scheduled expressions also have an empty request object.

Supported helper functions include:

Use CEL syntax, including null, &&, and !=. Python expressions such as is not None are not valid CEL. convert_time and make_readable are not registered helpers.

Escape literal braces as \{ and \}. YAML single-quoted strings are often convenient for CEL and backslashes. YAML double-quoted strings require their own escaping. Bash parameter forms such as ${NAME} also contain braces; escape literal braces when they are intended for Bash rather than CEL. $NAME avoids that particular ambiguity.

For JSON variables, the interpreter recursively evaluates strings in YAML maps/lists and JSON container strings. Object keys are evaluated too; two keys that evaluate to the same name cause an error. A string result containing valid JSON is decoded, so "123" can become a number and "{\"name\":\"Ada\"}" can become an object. Subsequent CEL expressions can address that structure.

Fallback candidates are separated by unquoted !>> outside CEL. Each candidate is tried in order. A failure is logged; the next candidate does not receive an error variable from the failed candidate:

message: ! ./message.sh !>> ! cat message.txt !>> "No message is available."

Inside a flow, exhausted fallbacks go to the action's catch branch, if present, or log and skip the action. Required compile-time settings still have to produce valid values; there is no usable configuration if its required identity or home cannot be evaluated. DNA entries and scheduling failures follow the behavior described above.

In block-style YAML, bare ! command notation is accepted. Inside inline collections, quote the complete expression:

assemble: ["! pwd"]

assemble: [! pwd] is rejected with a diagnostic because YAML would otherwise discard the anonymous tag. Multiline quoted strings and literal/folded YAML blocks are preserved by the parser. Avoid changing quotation just to silence an error without understanding whether it is YAML syntax, a CEL expression, a literal fallback, or shell argument quoting.

Bash runs as the current operating-system user, with the resolved home as its working directory. It receives SILICON_HOME and ISI. The runtime also gives Omni/provider sessions the configured TZ, SI_URL, and an ISI capability in SI_TOKEN.

Event flow

Every event requires this JSON shape:

{
  "type": "new_message",
  "data": {"message": "Hello"},
  "metadata": {"app": "example>app"}
}

type must be a string; data and metadata must be objects. Applications choose event types and fields. There is no special built-in routing for new_message, message_sent, or event; your flow decides what those types mean.

A flow is an ordered list of steps, or an expression producing a step or list. Steps can also appear in branches. A generated flow is validated before execution.

Consecutive if steps are independent. More than one can run. A trailing standalone else belongs to that entire consecutive chain, not only the last if. Any non-if action ends the chain. Use an else inside one if when you want an ordinary two-way branch.

flow:
  - var:
      name: incoming
      value: '{request.data}'

  - if:
      condition: '{request.type == "new_message"}'
      then:
        - send:
            isi: coordinator
            message: '{var.incoming.message}'
            catch:
              - log:
                  message: 'Delivery failed: {error}'
      catch:
        - log:
            message: 'Condition failed: {error}'

  - else:
      - log:
          message: 'Unhandled event type: {request.type}'

Catch branches receive a scoped string named error. Nested catches temporarily replace it and restore the outer error afterward. A catch does not leak error into later ordinary steps. Variables intentionally created inside a catch remain ordinary flow variables. Without a catch, an evaluation/action failure is logged and execution continues with the next step.

A flow send can create a missing session-addressed session automatically. An internal CLI send to a missing persistent session requires --new. This is a deliberate difference between flow routing and interactive session addressing.

Acknowledgment and delivery

An event response is sent after the entire flow has finished and its dispatched messages have received provider delivery receipts (START or INJECTED). It does not wait for inference turns to finish. Successful responses contain status: "ok" and an event_id.

Silicon forwards new messages immediately, including while an addressed session is working. It does not keep an interpreter queue waiting for a turn to end. Provider initialization and actual provider delivery can still take time. Delivery receipts have a 60-second deadline. Omni's provider behavior determines when an injection or native follow-up is acknowledged.

The ordinary send CLI returns session and delivery information after dispatch acceptance. show, logs, and Omni events reveal subsequent work. A completed model answer is not returned in the event acknowledgment.

Immediate expression/dispatch failures can trigger a send catch. A later delivery-receipt failure makes the event request fail after the flow has run; it does not replay the earlier catch branch. There is no general event deduplication or transaction rollback. If an upstream app retries an event after an uncertain response, already-completed actions can run again. Design side-effecting flows with that retry behavior in mind.

CLI reference

Use silicon --help, si --help, and subcommand help as the primary command reference. --json is global on both commands.

Interpreter commands

silicon compile PATH
silicon connect PATH
silicon disconnect ID_OR_PATH
silicon disconnect
silicon ls '*:my-org'
silicon logs show assistant:my-org
silicon logs show assistant:my-org --lines 200 --no-follow
silicon web
silicon web --no-open
silicon serve
silicon serve --port 1810 --no-proxy
silicon stop
silicon update

Without a command, silicon lists connections. silicon list is an alias for silicon ls. Quote globs so your shell does not expand them. disconnect without a target lists choices and prints the command to use; it does not disconnect everything.

serve stays in the foreground and is useful with a process manager. connect normally starts it automatically. --no-proxy is a development mode with direct localhost access and no Caddy aliases. This release does not install a login item, launch agent, or systemd service. After a reboot, use silicon serve or silicon connect to start the interpreter again.

Public work commands specify the Silicon identity first:

silicon send assistant:my-org coordinator "Please review this"
silicon send assistant:my-org worker.terminal "Build it" --id build-17 --new
silicon sessions assistant:my-org worker.terminal
silicon sessions assistant:my-org worker.terminal --archived '*release*'
silicon show assistant:my-org worker.terminal --id build-17
silicon end assistant:my-org worker.terminal --id build-17

Internal commands

si auth setup dm
si auth setup 'hook --profile work'
si auth remove dm

si isi send coordinator "Please review this"
si isi send worker.terminal "Build it" --id build-17 --new
si isi ls worker.terminal
si isi show worker.terminal --id build-17
si isi end worker.terminal --id build-17

si session new --archive-current-session \
  --id completed-release \
  --title "Release prepared" \
  --description "What was done, decisions made, and work remaining."

si needs the ISI context supplied by the interpreter. A normal terminal without SI_URL and SI_TOKEN cannot impersonate an ISI by setting only ISI. The server derives the caller from its capability, not from user-provided target fields.

si session new applies to the calling persistent session. --id, --title, --description, and --archive-current-session are required. --summary is an alias for --description. There is no si deliberate start-new-session command in this release.

Session behavior

Addressing and retention are separate choices:

For ephemeral work, an automatic reply goes back to the ISI session that invoked it through si, if that caller still exists. An external event or management send has no calling ISI to receive this reply; inspect logs or progress instead. A global ephemeral call always starts independent work, while a session-addressed ephemeral call can address its currently running ID.

Persistent sessions have both a logical id and an immutable Omni session_id UUID. The UUID is used for on-disk filenames. An archive name is data, not a filesystem path.

Archive and start a successor

si session new archives the current persistent session under the requested archive ID, title, and description. It preserves the original first timestamp and Omni session UUID and records the archive/completion timestamp. Duplicate archive IDs for that ISI are rejected.

For a global persistent ISI, the successor gets a new UUID-based logical ID. For a session-addressed persistent ISI, the successor keeps the old live logical ID; the archived predecessor gets the explicitly supplied archive ID. Both successors have a new Omni session UUID and fresh DNA. Authentication, Omni initialization, and DNA assembly finish before the rollover command returns.

Ephemeral sessions cannot create successors. A rollover does not copy the predecessor's entire prompt into the successor; durable memories and the new DNA provide continuity. Finish writing important context before asking to roll over.

End, inspect, and query history

show returns a session record and up to 100 recent provider events, without sending a message. With no ID, it selects the most recent active record. An explicit logical ID or Omni UUID can select an active or archived record.

end stops active work without creating a successor. A persistent session is archived; an ephemeral session is discarded. A restored persistent session can be ended without starting its provider. Omitting --id ends all active sessions of that ISI; use a logical ID or Omni UUID to select one.

Archived sessions are queried explicitly:

si isi ls worker.terminal --archived
si isi ls worker.terminal --archived 09:09:2026
si isi ls worker.terminal --archived 01:09:2026-09:09:2026
si isi ls worker.terminal --archived '*release*' 01:09:2026-09:09:2026
si isi send worker.terminal "Explain the deployment decision" --id completed-release --archived

An archived send accepts the archive's logical ID or its Omni UUID. It opens the archived conversation without converting it into a new active session. The answer returns to the calling ISI. The worker retires when its query is idle, while the archive and its conversation history remain.

Bare --archived selects the previous 72 hours. With explicit filters, the search covers all archive history. Filters intersect: a result must match every supplied date/range and text filter. Dates use DD:MM:YYYY; both ends of a range are inclusive. Text filters search title and description case-insensitively and support * and ?. A plain keyword can match a substring. Filters apply to the archive timestamp, using the Silicon's configured timezone unless --timezone IANA overrides it. They do not use the invoking shell's TZ by default.

IAM application contract

The interpreter owns orchestration of authentication. IAM issues short-lived application tokens. Each app exchanges and stores its own access/refresh tokens and maintains them afterward.

Configured login apps are checked on connection, before a new ISI session initializes, and before heartbeats. Apps added with si auth setup are remembered in the Silicon's managed-app registry and join those checks. A currently authenticated app can be reused. Removing an app from the dynamic registry does not override an app still listed in silicon.login; that configured app can be authenticated again at the next boundary.

The supported discovery contract is:

APP iam --json

It must succeed and return a JSON object with a nonempty string app_id, for example {"app_id":"tos>dm"}. Extra public discovery fields are allowed. Secrets must not be returned as ordinary discovery data.

The interpreter probes status in this order:

APP auth status --json
APP login status --json

One must provide a boolean authenticated. A false state can be reported with a nonzero exit code. A true state must also have a successful exit status. Invalid JSON, an absent boolean, or a transport error must not masquerade as successful authentication.

When authentication is needed, Silicon invokes IAM with its own identity:

iam --output json --org ORG silicon-login --sid LOCAL:ORG --stk SILICON_TOKEN --app-id APP_ID --grant-org ORG

IAM must return slt and a positive expires_in of at most 120 seconds. Only IAM receives the long-lived Silicon credential. Depending on the working status contract, the interpreter then invokes exactly one of:

APP auth token SLT
APP login SLT

It checks that the app reports authenticated: true afterward. It does not retry a different login spelling with the same potentially consumed one-use token. Captured token-bearing stdout/stderr is not forwarded to the Silicon log or exposed in the CLI result.

Removal supports auth remove, auth logout, or logout, selected through command help, followed by a false-status check. si auth setup returns the public app ID; it does not return the SLT or application tokens.

Application commands receive the Silicon home and the common isolated IAM home. App state should live under SILICON_HOME in an app-owned hidden directory. The interpreter sets SILICON_IAM_HOME to <SILICON_HOME>/.silicon-iam so it does not borrow the user's personal Carbon IAM session. A symlink used to redirect that credential directory is rejected.

For test worlds, the selected IAM environment and each application's paired test environment must agree. Merely importing an application into IAM does not create the app backend's own test plane. The real app test-plane creation APIs may require an authorized production control-plane identity; do not infer test success from iam --json alone.

Webhook expectations

An app listed in webhook must support:

APP webhook http://LOCAL.ORG.localhost
APP unhook

Registration happens after the Silicon route is added. A failed registration rolls back the connection and route as far as cleanup permits. Disconnect attempts every configured unhook and removes the Silicon and ISI capabilities even if one app reports an unhook error; it returns the cleanup error so the remaining app state can be investigated.

Apps should deliver the required event shape as JSON and consider the request acknowledged only on a successful response. They own upstream signature verification, session renewal, transport/retry policy, and any app-local relay. The local interpreter does not independently verify each app's remote webhook signature or require the Silicon token on the loopback event endpoint.

Files, storage, and logs

The default interpreter state directory is ~/.silicon-interpreter. SILICON_INTERPRETER_HOME selects another directory, useful for an independent test installation.

Session metadata includes the logical ID, Omni UUID, ISI, title, description, first/last timestamps, archive timestamp, status, normal-message count, and suggestion counters. Persistent data is saved atomically through a private temporary file and rename, with filesystem synchronization. State directories use mode 0700 and newly written state/log files use mode 0600 on Unix.

Short private aliases under /tmp/silicon-<uid>/ keep Omni socket paths within macOS's Unix-socket limit; session data remains under the Silicon home. Caddy gets a separate private temporary admin-socket directory. The interpreter never contacts the machine's default Caddy admin API.

Ephemeral work does not leave recoverable session records, event-history files, or its Omni session directory after retirement. Its operational activity can still appear in the append-only Silicon log. “Ephemeral” is a retention choice, not a promise that no log of the work exists.

Log entries have this shape:

[type] [origin] [UTC timestamp] [message]

Embedded message newlines are escaped so an entry stays on one line. silicon logs show ID prints the latest 100 entries and follows new ones. On a terminal, the type/origin prefix is colored, and the Silicon ID and log location remain in a footer. Ctrl-C restores the terminal and exits the viewer. --no-follow prints the tail and exits.

With --json --no-follow, the result is an object with silicon, path, and lines. With --json while following, each line is emitted as an independent JSON object containing silicon, path, and line. The follower handles appends, file replacement/truncation, and partial lines. There is no automatic Silicon log rotation or retention policy in this release.

Local dashboard and HTTP interface

silicon web opens the direct localhost dashboard with the current interpreter token in the URL fragment. --no-open prints that URL. The dashboard consumes the fragment, removes it from the displayed URL, and stores the token in browser session storage. Treat the printed URL and stored token as a management credential.

The dashboard can list, compile, connect, disconnect, send events/messages, inspect/end sessions, search archives, start successor sessions, authenticate/remove apps, and read/follow logs. Its log following polls the latest tail; the CLI follower is the continuous file-oriented view.

The underlying control API is POST /control with Authorization: Bearer <interpreter-token> and a JSON body of { "action": "...", "args": {...} }. The internal API is POST /si with the corresponding ISI capability. Events use POST / or POST /events on a connected Silicon hostname.

Requests require Content-Type: application/json and are limited to 16 MiB. Cross-origin browser requests are rejected. During shutdown/restart, requests are rejected with 503 so callers can retry after the interpreter resumes.

Security and lifecycle boundaries

Silicon configuration is trusted executable input. Bash scripts and inference-provider tools run with your user permissions. The access map and ISI capabilities restrict the supported internal API; they do not isolate malicious code running under the same operating-system account. A process that can read the Silicon's configuration or private state is inside that trust boundary.

The interpreter listens on loopback, and the owned Caddy configuration only forwards loopback clients for known hosts. Unknown hostnames and non-loopback peers are rejected, including forwarded-header attempts to impersonate loopback. The event endpoint trusts that local boundary rather than a per-event Silicon bearer token. Publishing or forwarding that endpoint publicly changes the security model and is not a supported installation step here.

The runtime omits the Silicon token from CEL's silicon object and removes SILICON_TOKEN and SILICON_INTERPRETER_TOKEN from the provider environment. The ISI receives only its own SI_TOKEN capability for internal API access. IAM credential state is scoped to the Silicon home, and the application receives a short-lived, app-specific token instead of the long-lived Silicon credential. Protect the original YAML and all credential-bearing files accordingly.

Explicit silicon stop, SIGINT, or SIGTERM stops the interpreter's owned workers and Caddy, removes the active daemon descriptor, and leaves saved connections and persistent state for restoration. This is a stop request, not a promise to let every model turn finish. App-owned relay daemons and saved authentication belong to those applications; disconnect calls their unhook, while stopping the interpreter preserves the saved connection configuration for later startup.

On startup, each saved YAML path is recompiled and reconnected. Failed restorations are logged and skipped rather than preventing every other Silicon from starting. Persistent session records are loaded when needed; provider processes are initialized lazily. A configuration file that was moved, removed, or made invalid can therefore fail restoration without being edited by the interpreter.

Caddy updates use its dedicated private admin socket. Accepted routes are persisted; a failed update retains or restores the previous routes. Cleanup stops only the Caddy process owned by this interpreter. Existing unrelated Caddy installations are not reconfigured or stopped.

Updates

Managed installations check GitHub's latest stable release once per hour while the interpreter is running. The first periodic check occurs after an hour. Drafts, prereleases, malformed version tags, and versions no newer than the running interpreter are not installed.

The updater uses the same embedded installer and checksum-verified complete bundle as public installation. It does not fetch a new shell script and execute it blindly, and it clears source-build/release-mirror overrides before the update install. Its logs are in the interpreter state directory's updates.log.

After successful automatic activation, the interpreter waits for active dispatches, nested activity, and pending provider work to finish. It then closes the admission gate, stops its owned children, and executes the newly installed interpreter. Connections and durable sessions are restored from disk. Incoming work is rejected once restart begins. Continuous active work can postpone the restart.

silicon update performs a manual check/install and reports whether a restart is required. After a manual update, use silicon stop followed by silicon serve when ready. The command reports the currently running version if there is no newer eligible release.

Set SILICON_AUTO_UPDATE=0 in the interpreter's environment to disable periodic updates. Source builds remain under your control and cannot use the managed-prefix update path. The interpreter, its CLI, and bundled dependencies can change together; YAML files, memories, workspaces, archives, and application state are never part of a release payload.

Troubleshooting

Useful environment switches are SILICON_INTERPRETER_HOME for interpreter state, SILICON_CADDY for the Caddy executable, OMNI_DAEMON for the Omni daemon executable, and SILICON_AUTO_UPDATE=0 for development runs. They affect the process in which they are set; an already-running daemon does not inherit new variables from a later terminal command.

The repository's reference template

stemcell/silicon, stemcell/memories, and stemcell/workspace are reference/testing material. The installer does not distribute them into user homes, and this implementation does not modify them.

stemcell/silicon/silicon.yaml is deliberately preserved as the supplied source of intent. It is not a ready-to-connect configuration. Its current issues include:

• silicon.id and silicon.token are ... placeholders.
• Several CEL interpolations contain text such as your time inside the expression without valid CEL syntax.
• It contains Python-style is not None, which must be expressed in CEL in a user's own configuration.
• It refers to convert_time and make_readable, which are not registered helpers.
• It refers to missing scripts/files including contacts.sh, tools.sh, team.sh, time_delay.sh, and learn.sh. The repository has CONTACTS.md, tools.md, and learn.md; those names do not make the scripts exist automatically.
• Some suggestion messages still show old command forms. Current rollover uses si session new --archive-current-session --id ... --title ... --description ....
• It mixes canonical settings with sticky and archive_on_end. The compatibility mappings above describe their actual meaning.
• Its repeated flow if keys and one unambiguously misplaced var field block are normalized by the dialect parser with warnings. Prefer an explicit step list and correct indentation in new files.

Correct a separate copy for your deployment. Compilation can report expression syntax before reaching the placeholder checks because syntax validation runs before any compile-time shell command. The absence of one particular placeholder error does not make the reference configuration valid.

Verification and requirement-to-evidence map

The current library suite completed with 21 passing tests and two Caddy-dependent tests excluded from the ordinary test run. cargo clippy --all-targets -- -D warnings passed. The ignored Caddy tests are explicit integration checks, not automatically verified by cargo test alone.

The protocol E2E uses the real pinned Omni daemon (0.7.2) and real Caddy, with a scripted Claude-compatible provider process for deterministic event behavior. It verifies the interpreter/Omni/Caddy protocol and lifecycle. Separately, a live run using the real authenticated claude-code-cli provider returned SILICON_SMOKE_OK and reached an idle session. That smoke test validates actual inference connectivity; it does not replace the deterministic concurrency/lifecycle assertions.

Reproducible development commands:

cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

# Supply the real executables; the E2E creates its own isolated work directory.
OMNI_DAEMON=/absolute/path/to/omnid \
SILICON_CADDY=/absolute/path/to/caddy \
python3 tests/e2e.py

SILICON_CADDY=/absolute/path/to/caddy \
cargo test --lib proxy::tests::real_caddy_routes_reload_rollback_and_child_cleanup -- --ignored

SILICON_TEST_BIN_DIR can select a built/installed interpreter directory for the E2E. It expects a real Omni daemon and real Caddy on PATH or through the overrides. It uses a free/available local test setup, creates its own YAML outside the template directories, and verifies that YAML's bytes remain unchanged. The LAN Caddy test additionally requires SILICON_TEST_LAN_IP set to this machine's non-loopback IPv4 address and port 80 available.

Source references for maintainers: src/config.rs, src/eval.rs, src/flow.rs, src/runtime.rs, src/auth.rs, src/state.rs, src/server.rs, src/proxy.rs, src/cli.rs, src/update.rs, src/dashboard.html, install.sh, .github/workflows/release.yml, and tests/e2e.py. The specification is UNDERSTANDING.md; the preserved fixture is stemcell/silicon/silicon.yaml.

Implementation diary

9 September 2026 · implementation diary

The 3.5 work establishes one Rust interpreter and a shared control surface for terminal and web operations. Configuration paths identify local connections; Silicon IDs identify their routed local hosts. Real Omni processes replace file-based send placeholders, and inference events drive delivery receipts, progress logs, and session lifecycle.

The parser preserves the reference dialect's ordered flow while rejecting ambiguous ordinary duplicate keys. Compatibility warnings make legacy addressing/retention fields visible. Expression validation covers unselected branches and fallback candidates before compile-time Bash can run. Login and webhook entries use a distinct deferred-command evaluation mode so configuration such as ! dm retains its intended app-command meaning.

Session work separates logical archive names from immutable Omni UUIDs. Persistent sessions retain metadata, conversation data, and history. Ephemeral sessions route a completed result to an internal caller and remove their recoverable data. Rollover creates a fresh persistent successor, preserves the predecessor's identity/timestamps, and retains the live address for session-mode work. Delivery and retirement tests cover callbacks, late failures, retries, and messages arriving around the end of a turn.

Scheduling evaluates DNA and heartbeat intervals at their documented boundaries. DNA assembly was moved off the provider event listener so refresh scripts do not block inference receipts. Suggestion counters exclude control messages and operate independently per session. Restart admission is coordinated with active dispatch and nested runtime work.

Authentication uses the installed IAM CLI's Silicon login contract, an isolated IAM state home, app discovery/status checks, and application-owned sessions. Dynamic app authentication is remembered for later session/heartbeat checks. Credential-bearing subprocess output is kept out of normal logs. The full authentication contract has controlled tests; live multi-app integration remains a separate verification task.

Caddy is owned by the interpreter and controlled through a private Unix socket. Route updates have rollback behavior and do not reconfigure an unrelated Caddy daemon. The installer builds or downloads complete bundles, verifies checksums, checks every required member, and changes the selected release only after preparation. Managed wrappers prevent dependency CLIs from independently updating the bundle.

Verification combines Rust tests, real Caddy integration, a real Omni protocol E2E with a scripted provider, and a separate actual Claude inference smoke test. The latter returned SILICON_SMOKE_OK. Release publication and documentation hosting should be recorded here only after they are complete and checked. No deployment claim in this diary is a substitute for that final evidence.

What the final integration runs caught

The real IAM 1.4.1 executable requires an explicit organization grant when minting an app token. Selecting --org only chooses context; it does not grant app access. The interpreter now passes --grant-org for the Silicon's own organization, and the contract check asserts it.

Restart testing exposed a saved-session edge case: end initially found only loaded workers. It now archives persistent sessions directly from disk without starting a provider, accepts the logical ID or Omni UUID, and serializes loaded-session ending with message acceptance. The E2E creates a session, restarts, and ends that unloaded session by UUID.

The updater was exercised against complete local release bundles with the real interpreter and Omni. Two test seams replaced GitHub metadata HTTPS with a loopback fixture and shortened the one-hour interval; those seams exist only in the test source copy. Equal/older versions, drafts, prereleases, bad checksums, and unmanaged builds were rejected appropriately. Successful activation preserved YAML and connections. During active work, version 3.5.0 kept serving after the new bundle was installed; only after provider completion did it execute 3.5.1 with the same PID and port, restore the session UUID, and resume work. This found and fixed ordinary shutdown incorrectly marking completed work as an error. GitHub's live transport and the literal hour-long wait are outside that accelerated check.

Browser verification covered configuration validation and connection, sending and injecting into a running turn, displaying provider completion, persistent rollover, and archive filtering. Mobile checks caught a connection-table overflow and a navigation handler that returned false while closing the menu, cancelling its link. The table now stacks at narrow widths and mobile documentation links navigate normally. The dashboard also retains the initial URL-fragment token for its browser session.

The complete source install and packaged install were tested in isolated prefixes. All 16 payload executables/wrappers were present, pinned Omni and Caddy versions matched, six application discovery commands returned IDs, and the installed bundle passed the protocol E2E. Package extraction and relocation preserved payload bytes, notices, wrapper behavior, and installation metadata. This is separate from live app authentication and from the four-platform release build.