Sculptured docs

CLI reference

Every command and flag of the sculptured program, with defaults and examples.

sculptured is one program with several commands. On a connected computer it runs as a background service, so you rarely type it yourself. Use these pages when you want to change what a computer allows, run Sculptured entirely on your own machine, or script a setup.

sculptured <command> [options]
CommandWhat it does
connectLink this computer to a Sculptured account and run that account's agents here.
allowLet agents from your account work in one more folder on this computer.
serveRun a complete Sculptured on this computer: the app, its data and a local runner.
hostdRun only the agent runner, dialling a Sculptured server. serve normally starts it for you.

sculptured --version prints the version. sculptured <command> --help prints the flags of one command.

flowchart LR
  subgraph you["Your computer"]
    C["sculptured connect<br/>(runner)"] -- "starts" --> A["Claude Code / Codex agents"]
    AL["sculptured allow"] -- "edits runner.json" --> C
  end
  C -- "outbound websocket" --> H["Sculptured account<br/>(hosted)"]
  subgraph self["Self-hosted"]
    S["sculptured serve"] -- "starts" --> HD["hostd (local runner)"]
    HD -- "starts" --> A2["agents"]
  end

sculptured connect

Links this computer to an account and keeps a runner connected, so the account's agents start here. The connect command you copy from the Computers page calls this for you, with a one-time key and --install-service.

sculptured connect <origin> [options]
Argument or flagDefaultMeaning
<origin>requiredThe account's address, for example https://app.example.com. A trailing / is ignored.
--key <KEY>noneA one-time connect key from the Computers page. With a key, the computer connects with no code to approve. A key works once, for 30 minutes.
--name <NAME>the computer's hostnameHow this computer appears in your account.
--allow <FOLDER>your home folderA folder agents may work in. Repeat it for more folders. When no folder has ever been allowed, your home folder is allowed. Add more later with sculptured allow.
--install-serviceoffInstall a login service, so the runner starts again whenever you log in, and return. Without it, connect stays in the foreground until you stop it.
--sandboxedoffLimit agents: Claude Code asks before risky actions, and Codex writes only inside its folder. Cannot be combined with --full-access.
--full-accessonLet agents act as you do on this computer. This is the default.
--enable <CAPABILITY>see belowTurn on something the account may do here. Repeatable.
--disable <CAPABILITY>see belowTurn off something the account may do here. Repeatable.
--data-dir <DIR>~/.sculptured/runnerWhere the runner keeps its settings, its saved pairing and its agents' records. Created readable by you only.
--claude-program <PATH>found on PATHThe Claude Code program to run.
--codex-program <PATH>found on PATHThe Codex program to run.

Capabilities

Beyond starting agents, an account may ask a computer to do a few other things. Each one can be switched off. The names below are what --enable and --disable accept.

CapabilityDefaultWhat it allows
gitonGit status, diffs, staging, commits and branches in an allowed folder.
copiesonEach agent working in its own Git copy of the project.
checkson with full access, off when sandboxedRunning a team's check commands (tests and similar) in its folder.
cli-sign-inonStarting Claude Code's or Codex's own sign-in from the browser.
plan-usageonReading your Claude or Codex plan usage.
generateonOne tool-less Claude Code or Codex call that drafts a team for you.

A capability you never set follows the access level. For example, switching to --sandboxed turns checks off unless you turned them on by name.

Without a key

If you run connect with no key and this computer is not yet linked to that address, it prints a link and a code:

To connect this computer, open:
  <link>
and confirm the code <code>

It also opens the link in your browser. Sign in, check that the code matches, and approve. The pairing is saved, so later runs reconnect without asking.

Login services

--install-service writes and starts one service for your user. It never needs administrator rights.

macOS

A LaunchAgent at ~/Library/LaunchAgents/dev.sculptured.runner.plist, loaded with launchctl. It starts at login and restarts if it stops.

Linux

A systemd user service at ~/.config/systemd/user/sculptured-runner.service, enabled and restarted with systemctl --user.

Windows

A Scheduled Task named Sculptured runner, which runs when you log on. Its definition is kept at %USERPROFILE%\.sculptured\runner\sculptured-runner.xml.

The service records the full paths of Claude Code and Codex, because a login service starts with a shorter PATH than your terminal. Running connect --install-service again replaces the old service, so a newly installed runner takes over.

Examples

# What the Computers page's command does on macOS and Linux
curl -fsSL https://app.example.com/install.sh | sh -s -- --key <KEY>

# Connect, allow two project folders, keep it running after login
sculptured connect https://app.example.com --allow ~/code/site --allow ~/code/api --install-service

# Sandboxed agents, and no Git operations from the browser
sculptured connect https://app.example.com --sandboxed --disable git

Exit codes

CodeMeaning
0Finished: the service was installed, or the runner stopped normally.
75A runner is already running with this data folder.
1Any other error. The message is printed after sculptured:.

sculptured allow

Adds a folder agents may work in. Agents and every file operation stay inside allowed folders, after .. and symbolic links are resolved.

sculptured allow <folder> [--data-dir <DIR>]
Argument or flagDefaultMeaning
<folder>requiredThe folder to allow.
--data-dir <DIR>~/.sculptured/runnerThe runner's data folder, if you connected with a different one.

It prints the full list of allowed folders. Restart sculptured connect, or its login service, so running agents see the change.

sculptured allow ~/code/new-project

sculptured approve-component

sculptured approve-component <digest> [--data-dir <DIR>]

Lets agents on this computer use a component that is not built in. The digest is in the note on the agent that went without it, next to what the component runs or connects to. Approve only what you would run yourself. Agents given the component start it at their next launch; nothing is restarted. A changed manifest has a new digest and needs approving again.

sculptured doctor

sculptured doctor [--data-dir <DIR>]

Checks what this computer has for its agents and prints one line each: Claude Code and Codex (installed, signed in), the built-in components' programs, and for each runner its allowed folders, how many components are approved here, and the names of component secrets set here (never their values). Lines marked fix need something done. It changes nothing.

sculptured set-secret

sculptured set-secret <NAME> [--remove] [--data-dir <DIR>]

Keeps a secret that a component names as ${NAME} (such as a remote MCP server's key) on this computer, for every runner here, or only the one in --data-dir. You type the value; it is not shown. You can also pipe it in. The value is never given on the command line, and never leaves this computer: the runner fills it in when it starts an agent. Agents pick it up at their next start. --remove forgets it.

sculptured serve

Runs a complete Sculptured on your own computer: the web app, its database and a local runner that starts your agents. See Run it yourself.

sculptured serve [options]
FlagDefaultMeaning
--port <PORT>4410The port to listen on. Sculptured listens on 127.0.0.1 only.
--data-dir <DIR>~/.sculpturedWhere projects, transcripts and settings are kept. Also read from SCULPTURED_DATA_DIR.
--web-dir <DIR>web/distThe built web app to serve. An installed copy uses ~/.sculptured/web.
--claude-program <PATH>found on PATHThe Claude Code program to run.
--codex-program <PATH>found on PATHThe Codex program to run.
--hostedoffUsed by the hosted service only: serve one user behind the gateway, with no local runner. Needs SCULPTURED_GATEWAY_SECRET.
~/.sculptured/bin/sculptured serve --port 4410 --web-dir ~/.sculptured/web

Then open http://127.0.0.1:4410. The runner is started in its own session, so pressing Ctrl+C in the terminal does not stop your agents.

serve runs on macOS and Linux. On Windows, connect the computer to an account with sculptured connect instead.

sculptured hostd

Runs only the agent runner and dials a Sculptured server. serve starts one for you; run it yourself only when you know you need a separate runner.

FlagDefaultMeaning
--controld <URL>requiredThe server's runner address.
--host-id <ID>localThe id this runner reports.
--data-dir <DIR>requiredWhere the runner keeps its records.
--token <TOKEN>requiredThe runner's token. Read from SCULPTURED_HOST_TOKEN when not given; it is removed from the environment before any agent starts.
--claude-program <PATH>found on PATHThe Claude Code program to run.
--codex-program <PATH>found on PATHThe Codex program to run.

Environment variables

VariableUsed byMeaning
SCULPTURED_DATA_DIRserveSame as --data-dir.
SCULPTURED_HOST_TOKENhostdSame as --token.
SCULPTURED_ARENA_URLserveWhere the Tests pages reach arenad, the test engine. The default is http://127.0.0.1:4510. Not used with --hosted.
SCULPTURED_KEYthe Windows installerThe one-time connect key the PowerShell command passes to connect --key.
RUST_LOGevery commandHow much the program logs to standard error, for example RUST_LOG=debug. The default is info.

Next steps