Install Agent Studio

Agent Studio is a local workspace for building Sapiom agents with Claude Code. It combines a coding-agent session with project discovery, a deterministic Canvas, local testing, deploy actions, and production runs. Choose the desktop host when you want a native app with a managed runtime, or the command-line host when Node and Claude Code are already installed.

Desktop app

The desktop app is available for the platforms represented by the current stable release assets:

Platform	Package
macOS on Apple silicon	Download .dmg
Windows x64	Download .exe
Linux x86_64	Download AppImage
Debian or Ubuntu on amd64	Download .deb

1. Install the package. On macOS, open the .dmg, drag Sapiom to Applications, and open it there. The current Mac release is signed and notarized. On Windows, run the .exe. On Linux, install the .deb through your package manager or make the AppImage executable before opening it:

   chmod +x ~/Downloads/Sapiom-Linux-x86_64.AppImage
   ~/Downloads/Sapiom-Linux-x86_64.AppImage

2. Let Studio prepare its runtime. You do not need to install Node separately for the desktop app. It supplies Node, npm, and npx support. When the environment check finds no coding-agent runtime it can use, Studio attempts a per-user Claude Code installation.

3. Connect your Sapiom account. Studio reuses a credential already stored at ~/.sapiom/credentials.json. On a clean desktop install, it opens browser sign-in before opening the main window. If authentication is cancelled or unavailable, Studio continues signed out: local project inspection and Local Run remain available, and you can connect from the account menu before a cloud action.

4. Choose session sharing. First launch asks whether to share detailed prompts, tool calls, and session events with Sapiom. This is off by default. The lighter product-analytics setting is separate and can be changed in Studio.

5. Open the welcome screen. Studio chooses the most recent valid folder or prepares ~/.sapiom/harness, then opens without starting a Claude Code session. Choose Open folder for existing work or Browse templates for a runnable starter.

Verified release baseline

These download and signing notes were checked against Agent Studio 0.1.5, published August 4, 2026, and the command-line flow was checked against @sapiom/[email protected]. There is no Intel Mac or Linux ARM release asset.

Command line

Use this host when you already have:

• Node.js 20 or newer;
• Claude Code installed as the claude command on your PATH; and
• network access for the first uncached npx and local-authoring MCP downloads.

From the folder where you want Studio to work, run:

npx @sapiom/agent-studio@latest

Or pass one existing folder explicitly:

npx @sapiom/agent-studio@latest ./my-project

The command-line launch verifies Node 20+ and reports Claude Code and Git availability. Git is useful for project workflows, but its doctor result does not prevent Studio from opening. The command does not install Claude Code for you.

On first launch, Studio asks about detailed session sharing, starts a local server on 127.0.0.1:4100, prints its tokenized URL, and opens that URL in your browser. It deliberately does not start a Claude Code session until you choose a folder or template. Keep the terminal running while Studio is open; press Ctrl+C to stop the server and its managed sessions.

The command-line launch reuses cached credentials and otherwise opens signed out. Sign in from the account menu before a deploy or production run, or add --login to perform browser sign-in before Studio starts. Local project inspection and local runs remain available while signed out.

Browser did not open?

Start again with --no-open, then open the complete tokenized URL printed in the terminal. Opening bare http://localhost:4100 does not carry the local boot token.

What you see first

Released @sapiom/[email protected] first-open screen. No coding-agent session is running yet; the launch folder is listed so it can be reopened.

Configuration boundary

Agent Studio generates the MCP configuration, authoring instructions, and Claude Code settings for each Studio session. It does not edit your global Claude Code settings, subscription, or model choice. Local project files stay on your machine until you explicitly use an authenticated cloud action such as deploy or production run.

Next steps

Tour Agent Studio Learn what the workspace rail, sessions, Canvas, Steps, and Code surfaces represent.

Build your first agent Create, check, and run an agent locally before deploying it.

Uninstall

Stop a command-line Studio with Ctrl+C; npx does not install a global Studio executable. For the desktop host, quit Sapiom and use your operating system’s normal application-removal flow.

Removing the app does not remove ~/.sapiom/harness session and workspace state, session-directory .sapiom/ files, shared credentials, or Claude Code history. Review Account and privacy and the Agent Studio file reference before deleting any of those separately.