SpaceApp Installation Experience Upgrade: From One Command to Your First Page

SpaceApp is a self-hosted AI coding workspace that runs AI coding CLIs inside isolated "rooms." Each room organizes a single task, and every panel within a room is an independent CLI or application session. Supported runtimes include OpenCode, Codex, Gemini, Qwen Code, Kimi Code, Grok Build, and an experimental DeepSeek CLI; Claude Code has a separate, owner-initiated installation flow.

Several recent installer releases have focused on the same stretch of experience: the time between running the installer and getting your first useful answer. This article breaks down that path step by step and explains what changed at each stage.

Installation: One Command and a Clear Bar

SpaceApp requires Linux, macOS, or Windows 11, Node.js 20.11 or newer, and at least 4 CPUs, 8 GB of RAM, and 15 GiB of free disk space. For the standard configuration (which adds a managed browser), 8 CPUs, 16 GB of RAM, and 25 GiB are recommended.

npx --yes run-spaceapp@latest install

The launcher manages the core API and web app, the various CLI runtimes, PostgreSQL, and Temporal. The default lightweight configuration does not include managed Chromium; the standard configuration also spins up a browser container. This "one command installs everything" approach consolidates what used to be scattered dependency orchestration into a single entry point, which is quite friendly for self-hosted scenarios.

Temporal is an open-source durable execution workflow engine. In an AI coding workspace, an agent task often involves multiple steps: reading files, calling tools, waiting for human confirmation, and retrying failed operations. If a process crashes or restarts, ordinary code loses its execution state. Temporal records the state of each step in an event history, so a recovered service can resume from the breakpoint instead of rerunning from scratch. Including Temporal in the default installation means panel sessions and task orchestration gain crash-recovery capability, which is especially useful for long-running coding agents. For self-hosted users, it also means maintaining an additional Temporal service instance.

PostgreSQL plays the role of persistent storage here, typically holding workspace metadata, session records, and task state, working together with Temporal's event history to form the state layer. The installer orchestrates both together, saving users the step of deploying and configuring connections separately.

Creating the Owner Account: Registering a Workspace Is a Prerequisite

Once the installation passes the readiness check, you need to create the first account using a one-time setup token, register the folder you want the agent to work in, and connect providers via their official login flows or masked credential entry.

Host folders are only visible after they've been registered as workspaces; read-only mounts are also supported. This is worth noting: it's not simply "granting access to a directory" but explicitly bringing directories into the workspace model, resulting in clearer permission boundaries.

This update adds three copyable first prompts to the "Ready" step of the setup wizard, reducing the blank-page feeling of "I've installed it, now what?"

The First Model: Verified by a Real Tool Call

The first OpenCode panel starts with a free model called Big Pickle. A model is only considered "usable" after it completes a real tool call: it must use its own read tool to read a small file and answer with the random token contained in it. If Big Pickle fails this check, the system switches to the latest free model that supports tool calling.

This acceptance criterion is much stricter than "it can return text." The upstream of free models can change at any time; if the model you're using stops responding, you can pick another one in OpenCode.

Tool calling refers to a model's ability, beyond generating text, to output structured call requests that let the runtime perform actions like reading files or running commands, then return the results to the model to continue reasoning. It's a foundational capability of coding agents: without tool calling, a model can only "talk" and not "do." That's precisely why merely verifying that a model can return text isn't enough to establish that it's usable—a model might support conversation but not function calling, or might not conform to the runtime's requirements in its call format. SpaceApp uses "read a small file and answer the random token inside it" as the acceptance test, which in practice checks three things at once: whether the model initiates a tool call, whether the runtime executes it correctly, and whether the result is correctly consumed by the model. This is much closer to real usage scenarios than a simple connectivity test.

The First Prompt: Two Issues That Used to Block New Users

According to the original article, there used to be two obstacles here.

Rooms without a project had nowhere to write. Now, CLI panels in such rooms start from /workspaces/<room>, so a first prompt like "build me a page" writes index.html there.

The first task could get stuck on a permission prompt. On macOS, the first OpenCode task used to hang on "access external directory /tmp" waiting for a manual response. Now OpenCode's first run only authorizes its own private staging directory, and the bootstrap instructions also send temporary files there; other paths outside the workspace still trigger a prompt. This effectively tightens the "default allow" scope to the minimum necessary set, reducing interruptions without expanding the permission surface.

The workspace model is key to understanding permission boundaries. In SpaceApp, host directories are not automatically visible to the agent; only after being explicitly registered as a workspace do they enter the accessible scope. Unregistered paths are outside the boundary by default and require manual confirmation. This is similar to the container mount approach: what gets mounted, and whether it's mounted read-write or read-only, are all explicit decisions. /workspaces/<room> is the default working directory within a room; CLI panels start from it, giving files produced by the first prompt a definite destination rather than scattering them in the process's current directory or a temporary directory. Understanding these two layers—workspace registration determines "what can be seen," and the panel's starting directory determines "where things are written by default"—helps troubleshoot issues where the agent can't find files or fails to write.

Staying Updated: In-App Prompt and One-Click Copy

When a newer version exists, the app now shows "Update available" and opens the update command with a copy button:

npx --yes run-spaceapp@latest update

For self-hosted tools, how smooth the update path is often determines whether users keep up with versions over the long term. Presenting the command directly in the UI is more practical than making users dig through documentation.

Things to Know Before Trying It

SpaceApp is designed for a single trusted owner on a single self-hosted instance, which determines its security model assumptions: it doesn't defend against lateral attacks in multi-tenant scenarios.

Backups are portable and checksummed, covering application data, PostgreSQL, and owner memory; however, provider credentials, login state, workspace content, and browser profiles are not included in backups. This means that when migrating or restoring, credentials need to be reconnected and workspace data must be managed separately.

Telemetry is opt-in. Answering "no" sends nothing; answering "yes" sends an anonymous event when the agent completes its first answer, including event type, random ID, version, CPU architecture, and date.

The author is also soliciting feedback: where the first five minutes still break down, your operating system, the configuration the installer chose, and the step where you got stuck. Full release notes can be found on the releases page of the GitHub repository.

For people who want to run AI coding agents on their own machines without handing their code over to third-party hosting, this kind of attempt—baking installation, model acceptance, and permission boundaries into the product flow—is worth watching.

Single-owner self-hosting is a deliberate security model trade-off. SpaceApp assumes that one instance serves a single trusted user, so it doesn't build multi-tenant isolation or cross-tenant permission checks. Under that assumption, omitting these protections is a reasonable design simplification; but once the instance is exposed to multiple people, or untrusted input is allowed to drive the agent, the original assumption no longer holds. Likewise, the backup scope excludes provider credentials, login state, and browser profiles because these are often bound to specific machines and sessions, and reconnecting after migration is safer than copying. When evaluating tools like this, confirming that their threat model matches how you intend to use them is more important than comparing features item by item.