README
¶
███████╗███╗ ███╗██╗████████╗██╗ ██╗███████╗██████╗ ███████╗ ██╔════╝████╗ ████║██║╚══██╔══╝██║ ██║██╔════╝██╔══██╗██╔════╝ ███████╗██╔████╔██║██║ ██║ ███████║█████╗ ██████╔╝███████╗ ╚════██║██║╚██╔╝██║██║ ██║ ██╔══██║██╔══╝ ██╔══██╗╚════██║ ███████║██║ ╚═╝ ██║██║ ██║ ██║ ██║███████╗██║ ██║███████║ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚══════╝
Automate maintaining your codebase
Smithers maintains your codebase. It turns issues into tested changes for you to review and, when enabled, keeps the project wiki current. Flows beside your code define how.
Open Smithers
Open the Smithers repository in your browser. Explore its files, ask questions in chat, and inspect runs and changes in the conversation. Sign in with GitHub when you are ready to contribute. Follow the app quickstart.
For local execution and authoring, use the CLI and libraries described below.
Supported platforms
The release candidate's required platform is Linux with Node 26.4.0. See the support matrix.
Install
The libraries install from npm; start with the Flows quickstart. Install the CLI from npm (Installation):
npm install -g smthrs@next
Get started
Run these commands from your project directory. Before launching, edit the
scaffolded flow and configure the credential its model: field requires.
The CLI quickstart covers each step.
smthrs init change
smthrs flow start change
[!TIP] Ask your agent to help you figure out how Smithers can help you and your project, based on everything it knows about you.
Documentation
Read the Smithers documentation for tutorials, guides, and the full reference. For the top-level build API, keep the Smithers API cheat sheet handy: one file of TypeScript examples covering the whole Smithers.* surface.
Contributing
See CONTRIBUTING.md for local setup, testing, and pull request guidance.
License
Smithers is MIT licensed. See LICENSE for details.
Join our community
Join the Smithers community on Telegram.
Directories
¶
| Path | Synopsis |
|---|---|
|
apps
|
|
|
backend
command
|
|
|
packages
|
|
|
backend/admission
Package admission exposes the shared, payment-key-free product quota policy.
|
Package admission exposes the shared, payment-key-free product quota policy. |
|
backend/apiclient
Package apiclient is the typed Go client of the Smithers product API.
|
Package apiclient is the typed Go client of the Smithers product API. |
|
backend/app
Package app is the public composition boundary for the Smithers product backend.
|
Package app is the public composition boundary for the Smithers product backend. |
|
backend/blobs
Package blobs exposes the canonical blob storage contract and integrity policy.
|
Package blobs exposes the canonical blob storage contract and integrity policy. |
|
backend/blobs/blobsconformance
Package blobsconformance provides adapter-neutral blob behavior checks.
|
Package blobsconformance provides adapter-neutral blob behavior checks. |
|
backend/canonicalimport
Package canonicalimport writes exported legacy rows directly into their canonical product tables.
|
Package canonicalimport writes exported legacy rows directly into their canonical product tables. |
|
backend/checks/C-SPK-05/profile
command
The calibration uses the production detector and limits, never a copied formula.
|
The calibration uses the production detector and limits, never a copied formula. |
|
backend/cmd/failurecodes
command
Command failurecodes renders Smithers' canonical failure-code registry.
|
Command failurecodes renders Smithers' canonical failure-code registry. |
|
backend/cmd/githubfake
command
githubfake is a loopback-only process for the local browser rehearsal.
|
githubfake is a loopback-only process for the local browser rehearsal. |
|
backend/cmd/legacyimport
command
Command legacyimport loads a sealed cutover archive into the product database.
|
Command legacyimport loads a sealed cutover archive into the product database. |
|
backend/cmd/resolve-agent-message
command
Command resolve-agent-message records an operator's reconciliation of an ambiguous message dispatch.
|
Command resolve-agent-message records an operator's reconciliation of an ambiguous message dispatch. |
|
backend/cmd/smithers-sftp
command
smithers-sftp is the bundle's stdio subsystem, executed after broker UID drop.
|
smithers-sftp is the bundle's stdio subsystem, executed after broker UID drop. |
|
backend/commerce
Package commerce exposes the canonical billing routes without a payment SDK.
|
Package commerce exposes the canonical billing routes without a payment SDK. |
|
backend/controlstore
Package controlstore gives deployment control services their consumed product queries.
|
Package controlstore gives deployment control services their consumed product queries. |
|
backend/credits
Package credits owns exact, transactional platform credit accounting.
|
Package credits owns exact, transactional platform credit accounting. |
|
backend/db/product
Package product owns the PostgreSQL schema shared by local Smithers and Plue.
|
Package product owns the PostgreSQL schema shared by local Smithers and Plue. |
|
backend/egressrelay
Package egressrelay is the workspace runtimes' credential-substituting egress relay (#3154).
|
Package egressrelay is the workspace runtimes' credential-substituting egress relay (#3154). |
|
backend/egressusage
Package egressusage reserves proxy byte allowances before the provider forwards them.
|
Package egressusage reserves proxy byte allowances before the provider forwards them. |
|
backend/errors
Package errors exposes the canonical product error and HTTP serialization contract.
|
Package errors exposes the canonical product error and HTTP serialization contract. |
|
backend/flowdispatch
Package flowdispatch durably maps product requests onto the canonical TypeScript Flow runtime.
|
Package flowdispatch durably maps product requests onto the canonical TypeScript Flow runtime. |
|
backend/flowhost
Package flowhost resolves product-owned bindings to authenticated instances of the canonical TypeScript Flow host.
|
Package flowhost resolves product-owned bindings to authenticated instances of the canonical TypeScript Flow host. |
|
backend/flowmanifest
Package flowmanifest verifies the host binaries supplied by a Smithers distribution.
|
Package flowmanifest verifies the host binaries supplied by a Smithers distribution. |
|
backend/flowruntime
Package flowruntime defines the deployment-neutral contract to the one canonical TypeScript Flow/Control host.
|
Package flowruntime defines the deployment-neutral contract to the one canonical TypeScript Flow/Control host. |
|
backend/hostexec
Package hostexec starts the programs the backend runs on its host.
|
Package hostexec starts the programs the backend runs on its host. |
|
backend/httpapi
Package httpapi exposes shared HTTP decoding, errors, pagination and audit context.
|
Package httpapi exposes shared HTTP decoding, errors, pagination and audit context. |
|
backend/installbundle
Package installbundle pins the installed server bundle a backend runs from and verifies, against that one pinned manifest, every file the host loads, runs or plants into a guest (spec §17.3).
|
Package installbundle pins the installed server bundle a backend runs from and verifies, against that one pinned manifest, every file the host loads, runs or plants into a guest (spec §17.3). |
|
backend/installbundle/bundletest
Package bundletest gives tests a directory an installed bundle or its state may live in: one reached through a protected chain.
|
Package bundletest gives tests a directory an installed bundle or its state may live in: one reached through a protected chain. |
|
backend/internal/billingstore
Package billingstore owns the shared billing query contract.
|
Package billingstore owns the shared billing query contract. |
|
backend/internal/buildcache
Package buildcache holds the pure half of the smithers build cache protocol: the bounds every deployment enforces, the canonical JSON rendering that decides whether two publications are the same result, and the validation of one action-cache publication.
|
Package buildcache holds the pure half of the smithers build cache protocol: the bounds every deployment enforces, the canonical JSON rendering that decides whether two publications are the same result, and the validation of one action-cache publication. |
|
backend/internal/chat/turncredential
Package turncredential is a hosted chat turn's platform-model credential.
|
Package turncredential is a hosted chat turn's platform-model credential. |
|
backend/internal/cleanup
Package cleanup provides utilities for cleaning up expired data.
|
Package cleanup provides utilities for cleaning up expired data. |
|
backend/internal/credentialscan
Package credentialscan detects credential material in text that must be safe to persist or publish.
|
Package credentialscan detects credential material in text that must be safe to persist or publish. |
|
backend/internal/githubfake
Package githubfake provides the GitHub HTTP boundary for install integration tests.
|
Package githubfake provides the GitHub HTTP boundary for install integration tests. |
|
backend/internal/githubrepo
Package githubrepo validates GitHub repository references shared by the mirror runtime and repository config sync, so both accept the same inputs.
|
Package githubrepo validates GitHub repository references shared by the mirror runtime and repository config sync, so both accept the same inputs. |
|
backend/internal/gitutil
Package gitutil shares git plumbing without choosing the caller's execution policy.
|
Package gitutil shares git plumbing without choosing the caller's execution policy. |
|
backend/internal/guest
Package guest implements the install's narrow, sponsored public interaction.
|
Package guest implements the install's narrow, sponsored public interaction. |
|
backend/internal/hostbackup
Package hostbackup validates and publishes quiescent host snapshots.
|
Package hostbackup validates and publishes quiescent host snapshots. |
|
backend/internal/identity
Package identity contains product-neutral identity boundaries shared by HTTP, Git, SSE, and SSH transports.
|
Package identity contains product-neutral identity boundaries shared by HTTP, Git, SSE, and SSH transports. |
|
backend/internal/lfsauth
Package lfsauth issues the short-lived, repository-scoped credentials used to bridge an authenticated SSH session to the Git LFS HTTP API.
|
Package lfsauth issues the short-lived, repository-scoped credentials used to bridge an authenticated SSH session to the Git LFS HTTP API. |
|
backend/internal/live
Package live reserves document admission for the shared live-channel adapter.
|
Package live reserves document admission for the shared live-channel adapter. |
|
backend/internal/livedocument
Package livedocument owns persistent native Yrs handles for the host document service.
|
Package livedocument owns persistent native Yrs handles for the host document service. |
|
backend/internal/machined
Package machined owns host-side boot and connection admission.
|
Package machined owns host-side boot and connection admission. |
|
backend/internal/machined/machinedfake
Package machinedfake is test support at the authenticated branch seam.
|
Package machinedfake is test support at the authenticated branch seam. |
|
backend/internal/machined/testfake
Package testfake supplies a data-only, scripted ADR 0004 peer for component tests.
|
Package testfake supplies a data-only, scripted ADR 0004 peer for component tests. |
|
backend/internal/machined/wire
Package wire owns ADR 0004 payload encoding.
|
Package wire owns ADR 0004 payload encoding. |
|
backend/internal/middleware
Package middleware — active-connection/subscription caps (ticket 0132).
|
Package middleware — active-connection/subscription caps (ticket 0132). |
|
backend/internal/observability
Package observability provides shared OpenTelemetry initialization for Smithers services (API server, repo-host).
|
Package observability provides shared OpenTelemetry initialization for Smithers services (API server, repo-host). |
|
backend/internal/ownership
Package ownership parses Smithers-generated OWNERS trees and GitHub CODEOWNERS files and resolves their policy for repository paths.
|
Package ownership parses Smithers-generated OWNERS trees and GitHub CODEOWNERS files and resolves their policy for repository paths. |
|
backend/internal/pkg/background
Package background runs slow work behind an instant answer: at most one job per key, with a failed job answered once to the next caller who asks.
|
Package background runs slow work behind an instant answer: at most one job per key, with a failed job answered once to the next caller who asks. |
|
backend/internal/pkg/crypto
Package crypto provides encryption utilities for sensitive data at rest.
|
Package crypto provides encryption utilities for sensitive data at rest. |
|
backend/internal/revocation
Package revocation propagates authorization revocations to every live consumer within seconds.
|
Package revocation propagates authorization revocations to every live consumer within seconds. |
|
backend/internal/routes
Package routes — approvals HTTP handler (ticket 0110).
|
Package routes — approvals HTTP handler (ticket 0110). |
|
backend/internal/services
Package services — approvals service (ticket 0110).
|
Package services — approvals service (ticket 0110). |
|
backend/internal/sse
Package sse provides utilities for Server-Sent Events backed by PostgreSQL LISTEN/NOTIFY.
|
Package sse provides utilities for Server-Sent Events backed by PostgreSQL LISTEN/NOTIFY. |
|
backend/internal/subscriptiontoken
Package subscriptiontoken is the one detector for a Claude or ChatGPT subscription login (#2178).
|
Package subscriptiontoken is the one detector for a Claude or ChatGPT subscription login (#2178). |
|
backend/ironproxy
Package ironproxy renders iron-proxy (docs.iron.sh) configuration for the per-sandbox credential-substituting egress proxy and the guest-side environment that routes traffic through it.
|
Package ironproxy renders iron-proxy (docs.iron.sh) configuration for the per-sandbox credential-substituting egress proxy and the guest-side environment that routes traffic through it. |
|
backend/jobs
Package jobs provides shared PostgreSQL admission, delivery receipts, and ordered product events for slow external operations.
|
Package jobs provides shared PostgreSQL admission, delivery receipts, and ordered product events for slow external operations. |
|
backend/localbootstrap
Package localbootstrap prepares the durable, single-owner backend instance used by both the container and the native application's local mode.
|
Package localbootstrap prepares the durable, single-owner backend instance used by both the container and the native application's local mode. |
|
backend/microsandbox
Package microsandbox runs every workspace in a local Microsandbox microVM.
|
Package microsandbox runs every workspace in a local Microsandbox microVM. |
|
backend/modelhost
Package modelhost connects the durable Go chat journal to the canonical TypeScript model host.
|
Package modelhost connects the durable Go chat journal to the canonical TypeScript model host. |
|
backend/modelprice
Package modelprice is the single checked-in price table for every model Smithers runs on platform keys.
|
Package modelprice is the single checked-in price table for every model Smithers runs on platform keys. |
|
backend/modelprice/cmd/generate
command
Command generate writes the TypeScript view of modelprice.Table.
|
Command generate writes the TypeScript view of modelprice.Table. |
|
backend/modelproxy
Package modelproxy is the one metering point for model calls made with a platform (Smithers-paid) provider key.
|
Package modelproxy is the one metering point for model calls made with a platform (Smithers-paid) provider key. |
|
backend/native
Package native composes the shared backend with packaged PostgreSQL for a desktop installation.
|
Package native composes the shared backend with packaged PostgreSQL for a desktop installation. |
|
backend/operations
Package operations exposes the canonical product collaborators needed by a deployment's control plane.
|
Package operations exposes the canonical product collaborators needed by a deployment's control plane. |
|
backend/operator
Package operator exposes server-free commands shared by hosted and local binaries.
|
Package operator exposes server-free commands shared by hosted and local binaries. |
|
backend/ports
Package ports defines the small set of dependencies that differ between a single-owner installation and a clustered deployment.
|
Package ports defines the small set of dependencies that differ between a single-owner installation and a clustered deployment. |
|
backend/postgres
Package postgres supervises the private PostgreSQL process of an owned local backend.
|
Package postgres supervises the private PostgreSQL process of an owned local backend. |
|
backend/process
Package process implements trusted single-owner workspace execution for an ordinary application container or native localhost process.
|
Package process implements trusted single-owner workspace execution for an ordinary application container or native localhost process. |
|
backend/productstore
Package productstore supplies the canonical product operations consumed by optional runtime adapters.
|
Package productstore supplies the canonical product operations consumed by optional runtime adapters. |
|
backend/provisioning
Package provisioning exports the canonical repository journal contract and product operations used by a deployment's placement adapter.
|
Package provisioning exports the canonical repository journal contract and product operations used by a deployment's placement adapter. |
|
backend/repository
Package repository exposes the shared native repository engine to the self-hosted app and to Plue.
|
Package repository exposes the shared native repository engine to the self-hosted app and to Plue. |
|
backend/runtimebridge
Package runtimebridge implements the authenticated, versioned JSON adapter to the canonical TypeScript Flow/Control host.
|
Package runtimebridge implements the authenticated, versioned JSON adapter to the canonical TypeScript Flow/Control host. |
|
backend/runtimeports
Package runtimeports defines deployment-neutral runtime collaborators.
|
Package runtimeports defines deployment-neutral runtime collaborators. |
|
backend/sandbox
Package sandbox defines Plue-owned sandbox DTOs, capabilities, and lifecycle boundaries.
|
Package sandbox defines Plue-owned sandbox DTOs, capabilities, and lifecycle boundaries. |
|
backend/sandbox/sandboxfake
Package sandboxfake is an in-memory sandbox.Provider for tests.
|
Package sandboxfake is an in-memory sandbox.Provider for tests. |
|
backend/security
Package security exposes canonical credential and request-context contracts.
|
Package security exposes canonical credential and request-context contracts. |
|
backend/ssh
Package ssh assembles the canonical product Git/SSH endpoint.
|
Package ssh assembles the canonical product Git/SSH endpoint. |
|
backend/telemetry
Package telemetry exposes the shared redacted instrumentation and logging pipeline.
|
Package telemetry exposes the shared redacted instrumentation and logging pipeline. |
|
backend/testkit
Package testkit constructs canonical product services for deployment adapter integration tests.
|
Package testkit constructs canonical product services for deployment adapter integration tests. |
|
backend/testkit/postgresfixture
Package postgresfixture opens product-schema databases for tests.
|
Package postgresfixture opens product-schema databases for tests. |
|
backend/testkit/postgresfixture/seed
Package seed inserts product rows for tests through the canonical product queries.
|
Package seed inserts product rows for tests through the canonical product queries. |
|
backend/testkit/testdb
Package testdb gives every PostgreSQL test its own freshly created database on the one server named by SMITHERS_TEST_DATABASE_URL, so test binaries run in parallel without sharing, resetting, or terminating each other's state.
|
Package testdb gives every PostgreSQL test its own freshly created database on the one server named by SMITHERS_TEST_DATABASE_URL, so test binaries run in parallel without sharing, resetting, or terminating each other's state. |
|
backend/webapp
Package webapp serves the same browser application from an owned or hosted backend.
|
Package webapp serves the same browser application from an owned or hosted backend. |
|
backend/webhooks
Package webhooks exposes the shared product event contract to deployment workers.
|
Package webhooks exposes the shared product event contract to deployment workers. |
|
backend/workspace
Package workspace defines the shared execution and workspace lifecycle.
|
Package workspace defines the shared execution and workspace lifecycle. |
|
backend/workspaceconformance
Package workspaceconformance contains provider-neutral behavior checks used by trusted-process and isolated workspace adapters.
|
Package workspaceconformance contains provider-neutral behavior checks used by trusted-process and isolated workspace adapters. |
|
smithers-machined/checks/C-SPK-08/gateway
command
Disposable SSH-to-session protocol probe.
|
Disposable SSH-to-session protocol probe. |
Click to show internal directories.
Click to hide internal directories.