Sculptured docs

Troubleshooting

Fixes for the problems people run into most, grouped by where they show up.

Find your symptom below and expand it for the likely cause and next step. For an agent that stopped unexpectedly, first open its pane and read the status notice. It often identifies the missing sign-in, connection problem or limit.

Connecting a computer

“There's no Sculptured build for … yet”

The Computers page offers only the systems the server has a build for, and the installer stops before installing anything if there is none. Build availability can differ by platform while a release is being published. Check the Computers page again after the build finishes, or connect a computer with an available build.

“Sculptured” Not Opened: Apple could not verify it is free of malware

The Mac app isn't signed with an Apple Developer ID yet, so macOS asks once. Click Done (not Move to Trash). Open System Settings → Privacy & Security, scroll to Security, click Open Anyway next to “Sculptured” was blocked, enter your password and click Open. See Install the Mac app.

The Mac app's icon is crossed out

That download doesn't run on this Mac's processor. Download the app again from the Computers page: the current Sculptured-mac.dmg runs on both Apple silicon and Intel Macs.

“checksum mismatch” or “could not download”

The download was cut off or changed on the way. Nothing was installed. Copy a new connect command from the Computers page and run it again.

The command worked once, but now it says the key is invalid

A connect key works once, for 30 minutes. Copy a new command from Computers → Connect a computer each time you connect.

“This computer was disconnected from its Sculptured account”

Someone pressed Disconnect for this computer, or its key was revoked. The runner stops instead of retrying. Copy a new connect command from the Computers page and run it on this computer: it notices the old key no longer works and connects with the new one.

I ran the Windows command again and it still doesn't connect

The Windows installer stops the previous runner before replacing its files, then starts the new one. If an older copy is still running from before that fix, stop it first:

  1. Open Task Scheduler, find Sculptured runner, and choose End, then Disable.
  2. In Task Manager, end any sculptured.exe and sculptured-background.exe.
  3. Run the connect command again in PowerShell.

The runner is installed in %LOCALAPPDATA%\Programs\Sculptured.

The computer shows as not connected after a restart

The runner starts again when you log in, not when the computer boots: a systemd user service on Linux, a LaunchAgent on macOS, or the Sculptured runner logon task on Windows. Log in to the computer. If it still doesn't appear, run the connect command again; running it again restarts the service.

Starting a team

The project's status says “Draft · N to fix” and Start team is off

The team has something to fix before it can start. Start team says why when you point at it. Click the status (Draft · N to fix, next to Start team in the project's tab row) to open the Design board, where Things to fix lists each problem; clicking one selects the agent, group or arrow it is about. Errors block starting; warnings don't.

“Connect a computer first: Computers → Connect a computer.”

With a Sculptured account, agents run on a computer you connect, and none is connected now. Open Computers, copy the connect command, and run it on the computer that has Claude Code or Codex. See Connect a computer.

“Choose which computer: more than one is connected.”

Several computers are connected, so Sculptured doesn't guess. Choose one under Runs on in the project panel on the Design board.

“… is not connected. Open Computers to connect it.”

The team is set to run on a computer that is offline. Turn that computer on and log in, or choose another computer under Runs on.

“…'s folder must be a full path”

A folder must start from the top of the disk: /home/you/project on Linux, /Users/you/project on macOS, or C:\Users\you\project on Windows. A path such as project or ~/project is not full.

“Sculptured can't read that folder”

The connected computer can't open the folder. On a Mac, Desktop, Documents and Downloads need your permission: in System Settings → Privacy & Security, allow Sculptured under Files and Folders or Full Disk Access, then choose the folder again. Elsewhere, check that the folder belongs to the user the runner runs as.

“… is not in a folder this computer allows”

The computer only lets agents start inside the folders its owner allowed. The installer allows your home folder. On that computer, run:

sculptured allow /path/to/folder

Or choose a folder inside one it already allows; Browse… shows only those.

“… does not exist on this computer”

The folder is typed for the wrong computer, or was moved. A team's folder is a path on the computer that runs it, not on the computer you're browsing from. Use Browse… to pick it.

Start says my plan is near its limit

Claude Code or Codex reported that your Claude or ChatGPT plan is at 90% or more of a usage window. Sculptured holds new work so a team doesn't stop halfway. Wait for the reset time shown, or press Start anyway. See Limits.

I can't edit agents or arrows

A running team's structure is locked: agents' settings, arrows, groups and folders. Names, jobs and positions can still change. Stop the team to change the rest.

Someone else saved this team

The team changed in another tab or window since you opened it. Sculptured keeps your version on screen and asks: Reload to take the other version, or Keep mine to save yours over it.

While a team runs

“Claude Code isn't signed in on the computer that runs …”

Claude Code (or Codex) is installed on that computer but not signed in, so the agent stopped at its first turn. Press Sign in to Claude Code in the agent's pane: it starts Claude Code's own sign-in on that computer and opens the sign-in page. After signing in, press Hand over again (or Restart) so the agent tries again.

You can also sign in by hand: run claude (or codex login) in a terminal on that computer as the same user. On Windows, if claude is not on your PATH, run & "$env:USERPROFILE\.local\bin\claude.exe".

Claude Code or Codex shows “not installed”

The computer couldn't find the program. Install it as the same user that runs Sculptured. Sculptured looks on your PATH, then in the usual install folders: ~/.local/bin, npm's, Bun's and Volta's folders, and Homebrew's on macOS; on Windows, %USERPROFILE%\.local\bin and %APPDATA%\npm. It looks again each time an agent starts, so you don't need to restart the runner.

“Live updates for … aren't arriving”

The board couldn't receive live updates for 8 seconds. Sculptured keeps trying in the background, and your agents are not affected. This is usually a dropped network connection, or a network or proxy that blocks live connections. Press Try again, or Open the Design board in the meantime.

An agent shows “stale” or “unknown”

Its computer's link was lost, so what you see is the last known state. Agents may keep working if the computer is awake and only its connection was lost. When it reconnects, Sculptured catches up. See When a computer drops off.

An agent is “stuck”

It is idle and its handoffs can't go on by themselves. The pane says why: often an upstream agent hasn't produced a result, or its turn was interrupted. Use Hand over again to resend the work it is owed, Resend handoff, or send it guidance.

An agent says “waiting for a slot to run”

It is not stuck. The team's run budget limits how many agents work at once, and that many are working, so its next message waits. It is sent by itself when a slot frees. To run more at once, raise Most agents working at once in Run budgets.

An agent's read was refused with “Sculptured protection: …”

Protections refused reading a large file whole, or a file outside the agent's contract. The agent is told why and how to read only the part it needs, and usually carries on by itself. To allow larger reads, change Advanced → Protections on the team; to allow those paths, change the agent's Contract. See Protections.

An agent continued in a fresh conversation by itself

Its context passed the team's protection limit, so between turns it wrote its notes to .sculptured/notes/ in its folder and continued in a fresh conversation from them. Every later step is then cheaper. The limit is in the team's Settings → More settings → Protections.

The Knowledge view says “No map yet”

A project map is made each time the team starts. If the team has started since then, the runner on the agents' computer is older than project maps: reinstall it from Computers. See What agents know.

An agent “needs attention”

It stopped when it shouldn't have, couldn't start, or was lost in a restart. Read the reason in its pane. Then Restart this agent, or answer the team's restore offer: Resume, Start fresh or Leave stopped.

An agent stopped saying a limit was reached

Its token limit, the team's output budget, or your provider's limit was reached. The first two are set on the team; see Limits. For a provider limit, Sculptured shows the reset time when the CLI gives one and never retries by itself: send "continue" after the reset.

Stop says “Stops as soon as its computer reconnects”

You stopped a team while its computer was offline. The agents stay stopping until the computer comes back, and are stopped then. If the computer is off, they aren't running anyway.

A question disappeared before I answered

Questions wait 10 minutes by default. After that the agent decides for itself and records what it decided; an answer you send later reaches it as an overriding instruction. A question is withdrawn only when it can no longer reach the agent, for example after the agent stopped.

Running it yourself

The port is already in use

Sculptured is probably already running. Open http://127.0.0.1:4410 instead of starting a second copy, or pass --port to use another port.

The page is blank or says it can't find the app

--web-dir must point at the built web app. Build it with npm ci && npm run build in web/, then start with --web-dir web/dist. See Run it yourself.

Opening Sculptured through another hostname is refused

The local app accepts only requests addressed to 127.0.0.1 or localhost. This is on purpose: it stops other websites from driving your agents. Don't put it behind a public proxy.

Agents keep running after I stop the server

The local runner can outlive the app, so restarting the app doesn't stop your agents. Stop teams in the app first if you want them stopped.

Gather details for a bug report