Waleed
f02ee99ce2
* feat(desktop,cli): support self-hosted desktop installs
The desktop shell was already origin-agnostic at runtime — navigation, CSP,
cookie partition, and the update feed all derive from the configured origin,
and every deployment already serves /api/desktop/update/download and its
updater manifest. The one thing missing was a way to change that origin:
ConfigStore.setOrigin had no IPC channel, menu item, or UI behind it, so a
self-hoster installing the signed build was stuck on the baked default.
Adds the native server picker (Sim → Server…, plus a "Change server" button on
the offline page, since a shell pointed at an unreachable origin lands there
with nothing else to click). Its IPC family is gated to bundled file: senders:
the surface that repoints the shell must keep working when the current server
cannot be reached, and must never be drivable by a page that server serves.
A confirmed change relaunches rather than swapping in place — the origin keys
the cookie partition, update feed, encrypted per-origin task state, and every
live browser view and PTY.
Adds `sim-setup desktop`, which resolves the installer from the operator's own
deployment, checks that the update feed resolves too, and prints the server URL
to paste in. Documents the whole path under self-hosting, including the
build-your-own escape hatch for organizations with their own Developer ID.
* refactor(desktop,cli): review pass on self-hosted desktop support
Two real defects found while auditing the change for hardcoded assumptions.
`lastRoute` is a single global setting that carries a workspace id, so it
survived an origin change and opened /workspace/<old-id> on the new server.
resolveStartRoute cannot rescue that — it discards a route only on a confirmed
403, and a fresh partition draws a 401. Cleared on change, via a named list
that is now the documented home for deployment-scoped settings; the agent
browser's jar and its known-sites metadata are deliberately kept, together,
since changing deployments does not imply the account changed.
The offline page's "Check status" sent self-hosters to status.sim.ai, which
reports on Sim's deployments and is always green for theirs. Withheld for a
non-sim.ai origin, as is the same link in the Help menu, through one
isSimCloudOrigin predicate. Hiding it needed `button[hidden]{display:none}`:
the page's own `button{display:inline-flex}` is an author rule and outranks the
UA `[hidden]`, so the attribute alone left it rendering. The e2e offline test
now asserts the whole path, which covers the `server:` local-page IPC gate.
Review cleanups: setOrigin no longer rewrites settings when handed the origin
it already stores; the picker window installs a permission handler and pre-
paints its background like every other window, and its page is theme-aware so
that background is not a flash; the CLI reuses httpHealth and the
cross-platform openBrowser instead of reimplementing both, skips Compose/Helm
discovery when --url makes it dead, and folds two parallel switches into one
exhaustive one. Value-flag parsing is now one helper instead of a third copy.
* fix(desktop,cli): scope deployment capabilities to their origin
Changing the server left two device-global stores in place that grant the
INCOMING deployment authority the user only handed the outgoing one: local
filesystem grants (directories its agent may read, plus security-scoped
bookmarks) and the agent browser's cookie jar (live third-party sessions its
agent may drive). Sign-out clears exactly this pair; an origin change is the
same boundary, so it now clears it too — awaited before the relaunch, since a
quit racing an async clear could leave either behind. browserKnownSites goes
with the jar it describes, so Sim is never left believing in sign-ins the
profile no longer has.
The CLI printed the redirect's filename straight to the terminal. It is read
out of a Location the deployment chose, so percent-encoded ANSI or OSC survives
decodeURIComponent as real control bytes and could forge CLI output; control
characters are stripped and the name is bounded before it reaches the spinner.
resolveDeploymentUrl took the first source naming an app URL. A machine with
both a local checkout and a real deployment would be probed, printed, and
opened at whichever enumerated first, silently — so disagreeing sources are now
an error naming each candidate and asking for --url, the way
resolveFeatureSetupDestination already refuses ambiguity.
* fix(desktop,cli): fail closed on origin change, widen terminal sanitizer
The capability teardown could partially fail and still let the shell move.
Sequential awaits meant a filesystem-grant rejection skipped the browser-profile
clear entirely, and the new origin was already persisted by then, so the
incoming deployment inherited whatever survived — and startup restores it.
Now the two stores clear independently via allSettled and report which ones
survived, and the whole teardown runs BEFORE anything is written. A store that
cannot be emptied refuses the change outright and names what it could not
clear. Nothing is persisted at that point, so refusing leaves the shell exactly
where it was rather than half-applying. Validation moved up front for the same
reason: a typo now costs no teardown.
The terminal sanitizer matched only C0/DEL/C1 by range, so percent-encoded bidi
overrides and isolates survived decodeURIComponent and could still reorder what
the reader sees without emitting one control byte. Matched by Unicode class
instead — Cc covers the cursor controls, Cf covers the bidi ones.
Configuration discovery compared raw strings, so a trailing slash, a default
port, a host-case difference, or an ignored path read as two different servers
and demanded a --url override to settle an ambiguity that did not exist. Now
compared on the parsed origin, which is what the command ends up using.
* fix(cli): sanitize the installer name by Unicode group, not by escape list
U+2028 and U+2029 are Zl/Zp, so the Cc/Cf filter let them through and a
deployment-controlled redirect filename could still forge a status line.
Enumerating what to strip had cost a patch per class found — C0 and C1, then
the bidi overrides, now the line separators — so this keeps whole groups
instead. `C` removes every control, format, surrogate, private-use, and
unassigned code point, covering ESC and OSC, the bidi overrides and isolates,
zero-width characters, and the BOM; `Z` removes every space, line, and
paragraph separator. Separators become a plain space rather than vanishing so
a name is not run together at the seam, and runs are collapsed so the result
cannot be padded to push text off the line.
The regression table now names each class that reached the terminal in an
earlier round, so a future bypass says which one came back.
* fix(desktop): serialize server changes and report partial teardown honestly
Two problems in the same transaction.
The picker re-enabled Connect whenever the field changed, including while a
request was in flight, so typing and pressing Enter could start a second change
that interleaved its teardown and its write with the first — the later write,
not a single transition, deciding the next server. The transaction is now
serialized in the main process, the way the sign-out coordinator guards its
own teardown, since the IPC boundary is reachable regardless of what the page
does; the page keeps its button disabled for the whole request so it never asks
for something it will only be refused.
The stores clear independently, so one can succeed while the other fails. There
is nothing to roll back to — a revoked cookie jar and deleted security-scoped
bookmarks cannot be un-deleted — and moving anyway would hand the incoming
deployment whatever survived. So the change is still refused, but the message
no longer names only the failed store as though nothing else had happened: it
says some local access may already have been cleared, and that retrying
finishes the job. Clearing an already-empty store succeeds, so a retry is safe.
Sim Setup
sim-setup is the installer and management tool for a self-hosted
Sim deployment. Sim is a workspace for building, deploying,
and managing AI agents and workflows.
For an npm user, sim-setup creates a Docker Compose installation from published
Sim images. It generates the required secrets, writes the deployment files,
starts the containers, runs database migrations, and checks that the application
is healthy. It does not clone the Sim repository.
This package installs the Sim server. To manage workflows, tables, files, and
other resources in a running Sim workspace, use the separate
sim CLI.
Requirements
- Node.js 20 or newer
- Docker with the Compose plugin
- Ports
3000,3002, and, by default,5432available - At least 12 GB of system memory and 20 GB of free disk for a small installation
Allocate at least 8 GB of memory to Docker for reliable workflow execution.
Docker Desktop, OrbStack, Colima, and Docker Engine are supported as long as the
docker command can reach the daemon.
Install and run
You normally do not need to install the package globally:
npx sim-setup
To install it globally instead:
npm install --global sim-setup
sim-setup
The examples below use npx; omit it if you installed the package globally.
The default standalone setup creates a sim directory under the current
directory:
sim/
├── .env
├── .sim-setup.json
└── docker-compose.prod.yml
Use --dir to choose an explicit location:
npx sim-setup --dir /srv/sim
When setup finishes, open http://localhost:3000 and create the first account.
What the setup wizard does
The wizard:
- checks Docker, available ports, memory, and disk space
- creates or reuses the installation directory
- generates authentication, encryption, internal API, and scheduler secrets
- optionally connects Sim Chat and model providers
- writes
.envand the managed production Compose file - starts PostgreSQL, Redis, the Sim application, realtime, and scheduled jobs
- runs migrations and waits for the health checks to pass
Choose Quick for sensible defaults and the fewest questions. Choose Custom to configure additional options such as object storage, email, sign-in providers, security settings, and self-hosted feature flags. Skip the prompt with:
npx sim-setup --quick
The wizard detects an existing installation. Re-running it lets you keep and
check the current configuration, review and update it, or archive the current
.env and build a new configuration. If setup fails partway through, fix the
reported problem and run the same command again; completed configuration is
preserved.
Chat and model access
Sim can run without the optional Chat API key. If you skip Chat setup, the wizard hides the Chat module instead of leaving it enabled but unusable. Connect or replace the key later with:
npx sim-setup add chat
npx sim-setup start
Agent blocks also need access to a model provider. Configure provider keys in a
workspace in the Sim UI, pass supported keys such as OPENAI_API_KEY or
ANTHROPIC_API_KEY into the setup environment, or add deployment-wide model
configuration later:
npx sim-setup add llm
npx sim-setup start
For Docker Compose installations, add updates .env but does not recreate the
application container. Run npx sim-setup start afterward to apply the changed
environment. restart only restarts containers with their current configuration.
Manage the installation
Run commands from the installation directory or pass --dir <path> to target a
specific installation.
| Command | What it does |
|---|---|
npx sim-setup status |
Show detected installations, container state, and app health |
npx sim-setup logs |
Follow the last 100 lines of Docker Compose logs |
npx sim-setup start |
Start or reconcile the containers; data is kept |
npx sim-setup stop |
Stop containers without removing them |
npx sim-setup restart |
Restart the current containers |
npx sim-setup update |
Refresh the managed Compose file, pull images, recreate services, and run migrations |
npx sim-setup down |
Remove containers but keep data volumes |
npx sim-setup reset |
Archive .env, remove containers, and delete managed data volumes |
down and reset are deliberately different. Use down when you want to
remove containers and bring the same installation back later. reset is a
destructive fresh start and asks for confirmation before deleting data.
Check configuration
config reports which effective configuration sources, capabilities, and OAuth
integrations were detected. It does not print secret values:
npx sim-setup config
doctor validates environment files, required values, cross-service
consistency, and live dependencies:
npx sim-setup doctor
npx sim-setup doctor --fix
npx sim-setup doctor --json
Use config to answer “what is configured?” and status to answer “what is
running and healthy?”
Install the desktop app
desktop resolves the macOS installer from your own deployment and prints the
server URL to enter in the app:
npx sim-setup desktop
npx sim-setup desktop --url https://sim.example.com
npx sim-setup desktop --no-open
The desktop app is not tied to sim.ai — it bakes in only a default server, and
every Sim deployment already serves /api/desktop/update/download and the
update feed installed apps poll. Install the signed build, then point it at your
deployment with Sim → Server…. Nothing has to be built or signed by you.
Add or change capabilities
Configure one capability without walking through the complete wizard:
npx sim-setup add email
npx sim-setup add storage
npx sim-setup add sandbox
npx sim-setup add jobs
npx sim-setup add cache
npx sim-setup add knowledge
npx sim-setup add knowledge-embeddings
npx sim-setup add chat
npx sim-setup add llm
npx sim-setup add integration slack
Run npx sim-setup start after changing a Docker Compose capability so the app
container receives the new environment.
Updating
Update a Docker Compose installation with:
npx sim-setup update
npx sim-setup status
The update command keeps Docker volumes, applies the current managed Compose
file, pulls the version selected by SIM_VERSION, and runs migrations. If
SIM_VERSION is unset, the deployment tracks latest.
For production, pin an explicit version, back up the database first, and read the upgrade guide. Docker Compose updates briefly interrupt the application because Compose does not provide rolling deployments.
Files, secrets, and data
The generated .env contains credentials and encryption keys. It is written
with owner-only permissions and must not be committed to source control.
Back up .env securely outside the server before using the deployment for real
data. In particular, ENCRYPTION_KEY and API_ENCRYPTION_KEY protect stored
credentials and API keys. A database backup restored without the matching keys
contains data that Sim cannot decrypt.
PostgreSQL data lives in a Docker volume. These commands preserve it:
startstoprestartupdatedown
reset deletes managed volumes. It archives .env beside the installation
before doing so, but that local archive is not a substitute for an off-machine
backup.
The default local file-storage fallback is different: uploaded files live inside
the application container, not in a managed volume. They can be lost when the
container is removed or recreated, including during down or update.
Configure object storage before keeping files you care about.
Production deployments
The generated Compose installation is suitable for local evaluation and a single-node deployment. Before exposing it publicly, configure at least:
- a public application URL and TLS reverse proxy
- database and
.envbackups - durable object storage for uploaded files
- email delivery for invitations and email-based authentication
- OAuth applications for integrations you plan to use
- a pinned Sim version and an upgrade procedure
See the Docker deployment guide and the complete self-hosting documentation.
Working from the Sim source repository
Inside a cloned Sim repository, use:
bun run sim-setup
The source checkout adds local development and Kubernetes modes:
bun run sim-setup --mode dev
bun run sim-setup --mode k8s
Standalone npm use supports Docker Compose mode only. Development and Kubernetes modes need source-only files and are rejected outside a complete checkout.
Help
npx sim-setup --help
npx sim-setup --version
Further documentation:
- Self-hosting overview
- Docker Compose
- Environment variables
- Upgrades
- Troubleshooting
- Verification checklist
License
Apache-2.0