Sculptured docs

Run it yourself

Build Sculptured from source, run it on your own computer, and back up, upgrade and roll back your data.

Run Sculptured locally to keep the app, runner and run history on your computer without a Sculptured account. The sculptured serve command serves the app on port 4410 and starts the runner. Sculptured stores its data in ~/.sculptured/; agents work in the project folders you choose. The app and runner are open source under Apache 2.0.

On your own computer

The app, database and agents run on your machine. Team designs and run history are stored locally, with no usage analytics. Claude Code and Codex still send context to their providers.

With a Sculptured account

The hosted beta runs your Sculptured for you, and your agents run on the computers you connect. See Connect a computer. You don't need anything on this page.

flowchart LR
  B["Your browser"] -- "http://127.0.0.1:4410" --> S["sculptured serve: app, API, database"]
  S -- "loopback link, host token" --> R["Local runner"]
  R -- "starts, sends messages, stops" --> A["Claude Code / Codex"]
  A -- "reads and writes" --> F[("Your project folders")]
  S -- "reads and writes" --> D[("~/.sculptured/")]

Before you start

You needWhy
Linux or macOSsculptured serve runs on Linux and macOS. On Windows, Sculptured runs only as a connected computer for a Sculptured account.
Rust 1.95 or newer and Node.js 24To build the program and the web app.
Claude Code or Codex, signed in as your own userSculptured uses their existing sign-in and never stores provider credentials.
GitFor agents' own copies of a repository and the Git panel.

Build and start

Clone the repository, then run the build steps from its root:

git clone https://github.com/Sculptured/Sculptured.git
cd Sculptured
  1. Build the web app
    cd web
    npm ci
    npm run build
    cd ..
    
  2. Build the program
    cargo build --locked --release -p sculptured
    
  3. Start it
    ./target/release/sculptured serve --port 4410 --web-dir web/dist
    

    Open http://127.0.0.1:4410. If Sculptured is already running, open that address instead of starting a second copy.

serve options

OptionDefaultMeaning
--port4410Port on 127.0.0.1.
--data-dir~/.sculpturedWhere Sculptured stores its data. Also read from SCULPTURED_DATA_DIR.
--web-dirweb/distThe built web app.
--claude-programfound on PATHFull path to Claude Code, if it is not on PATH.
--codex-programfound on PATHFull path to Codex, if it is not on PATH.

Sculptured logs to the terminal. Set RUST_LOG=debug for more detail. See the CLI reference for every command.

What's in ~/.sculptured/

PathWhat it holds
controld.sqlite (with -wal and -shm)Your teams, runs, messages, questions, transcripts and the event history.
host-tokenThe secret the local runner uses to connect to the app. Private to your user.
host-local/The local runner's own state: its journal, its lock, the address of the running app, and each agent's skills (skills/) and Signet-Eval rules (signet/).
copies/Agents' own copies of your repositories, when a team uses them. They can hold work not yet merged.
runner/Only on a computer connected to a Sculptured account: its identity and the folders it allows.

The runner can outlive the app. If you restart serve, the running runner finds the new app on its own, and running agents keep going.

Back up

The database uses SQLite's write-ahead log, so copying only controld.sqlite while Sculptured runs is not a reliable backup. Pick one:

While it runs

sqlite3 ~/.sculptured/controld.sqlite ".backup '/path/to/backup/controld.sqlite'"

Stopped

Stop Sculptured, then copy the whole ~/.sculptured/ folder.

Agents' copies in ~/.sculptured/copies/ are separate Git working folders. Merge or copy out their work before you delete them.

You can also keep a team outside the database: Export team file saves it as a .madl.yaml file, and Import loads one. See Team files.

Upgrade

  1. Stop running teams
    Stop every team in the app, so no agent is left working unwatched.
  2. Back up
    Take a backup as above.
  3. Replace the program and web app
    Build or copy the new sculptured and the new web folder. Keep the old program until you have checked the new one.
  4. Start again
    Run sculptured serve. It upgrades its database when it starts.

Roll back

Database upgrades are not reversed automatically. To go back to an older version, stop Sculptured, restore the backup you took before upgrading, and start the older program.

After a restart

Sculptured keeps teams, runs, messages and questions in its database. After a restart:

See States and evidence.

Other computers

A self-hosted Sculptured runs agents on the computer it runs on. To run agents on other computers, such as a Windows PC or a second laptop, connect them to a Sculptured account. See Connect a computer.

Next steps