Skip to content

daemon.md

Latest commit

 

History

History
144 lines (109 loc) · 6.24 KB

daemon.md

File metadata and controls

144 lines (109 loc) · 6.24 KB
Raw

Artifacts host

Run the full Artifacts application on your machine, including the gallery, coding agent connection, apps, scripts, storage, and schedules. Start it in a terminal:

bunx @sidequery/artifacts host

Open localhost:4786; connect your agent to http://127.0.0.1:4786/mcp. No sign-in is needed in this default local setup. Saved apps and data survive restarts. Ctrl-C stops the server.

For a background service, install the package globally with bun add --global @sidequery/artifacts, then use:

Command What it does
artifacts host start Start in the background
artifacts host status Show whether the service is ready and its URL
artifacts host logs Show recent logs
artifacts host stop Stop the service, keeping saved data
artifacts host install Start now and enable startup at login
artifacts host uninstall Stop and remove the service, keeping saved data

Background services use launchd on macOS or a systemd user session on Linux. On Linux, running before login requires user lingering or a system-level service. artifacts server is an alias for artifacts host and uses the same state. See celld deployment for running a network deployment.

Local persistent runtime

The native Artifacts server is optional. It runs the packaged Worker and its SQLite/KV state through a pinned celld runtime on 127.0.0.1. The ordinary Artifacts CLI, stdio MCP server, local gallery, and artifact commands do not start or download celld.

Foreground server

Run the server in the current terminal:

artifacts host

The default address is http://127.0.0.1:4786. --port selects another port. The server keeps its project and native state under the Artifacts data directory; --state-dir PATH overrides that project directory for a foreground run. Press Ctrl-C to request a graceful stop. SIGTERM uses the same shutdown path.

On first use, Artifacts downloads the pinned celld runtime for a supported platform, verifies the pinned archive and executable SHA-256 values, and installs it in the Artifact data directory with user-only permissions. This release supports Apple Silicon macOS and glibc Linux on arm64 or x64. The ordinary Bun commands do not require this native runtime; artifacts host reports an explicit error when the native platform is unsupported.

Background service

Use the operating system's user service manager for crash recovery:

artifacts host start
artifacts host status
artifacts host logs
artifacts host stop

start uses launchd on macOS and systemd --user on Linux. It first verifies the packaged server assets and managed celld executable, then registers the service and waits for owned-process readiness. A manual start does not newly enable login startup; an existing login setting is retained. stop unloads or stops the current job and waits for graceful shutdown. It retains the server project and all SQLite/KV data.

status reports the service manager and four separate facts:

  • installedAtLogin: the user explicitly enabled future login starts.
  • loaded: the service definition is currently known to the manager.
  • running: the manager reports a live main process.
  • ready: that process published matching PID, port, and state-directory readiness, and its loopback health endpoint responds successfully.

The URL appears only when ready is true, so an unrelated process on the same port cannot be reported as this Artifacts service. Service identities include a stable hash of ARTIFACTS_DATA_HOME, which prevents commands for one data root from stopping the service for another. Two roots still cannot listen on the same port; start checks for that conflict before registration.

logs prints the most recent 100 lines from the service log. Select between 1 and 1000 lines with artifacts host logs --lines N. Each read is capped at 256 KiB even when the log is larger.

Start at login

If the server is already running, stop it first. Then start it and opt in to future login starts:

artifacts host install

Install @sidequery/artifacts globally before enabling this option, for example with bun add --global @sidequery/artifacts. The supervisor definition records the exact Bun executable and absolute installed src/cli.ts path. Do not create a login service from bunx or another transient package cache: cleanup or cache rotation can remove that recorded path.

artifacts host stop stops the current process but preserves the login setting, so the service starts at the next login. Disable login startup, stop the service, and remove its installed supervisor definition with:

artifacts host uninstall

Run uninstall before moving or removing the global package. Enabling login is never part of package installation, upgrade, or publication.

Data and configuration

Set ARTIFACTS_DATA_HOME to choose a data root. Otherwise Artifacts uses:

  • macOS: ~/Library/Application Support/sidequery-artifacts
  • Linux: ${XDG_DATA_HOME:-~/.local/share}/sidequery-artifacts

The durable native project is under server, the managed runtime is under runtimes, and lifecycle state and logs are under daemon. On Linux, XDG_CONFIG_HOME selects the systemd user-unit directory when set.

Supervisor definitions forward ARTIFACTS_DATA_HOME and, for standalone binaries, the embedded interpreter/runtime settings. They do not copy the invoking shell's credentials or other environment variables. The native server binds only to loopback. Its state is local application data and is not uploaded or backed up automatically.

For bucket-backed production nodes, TLS/authentication boundaries, health checks, and graceful rollout guidance, see celld deployment.

For a trusted reverse-proxy deployment, set the Worker binding ARTIFACTS_PUBLIC_ORIGIN to its exact external origin (for example, https://artifacts.example). Generated artifact/script links, file-transfer URLs, and preview transfer policies use that origin. Request authentication and Origin checks still use the incoming request; forwarded headers do not override identity or the configured origin. Configure this binding in the deployment's Worker configuration; it is not a host CLI flag. Without it, URLs use the request origin.