AgentStudio

Self-hosted autonomous AI agent platform with user-scoped tool sandboxes and passkey authentication.

Feature Overview

Chat and Tooling

AgentStudio provides a streaming chat interface where the assistant can call tools such as web search and sandboxed code execution. The filesystem toolset supports ranged file reads, full writes, unified-diff patch apply, deterministic string replace, recursive directory listing, search, move/rename, delete, and file metadata lookups. Chat supports editing and branching, interleaved tool and thinking blocks, per-message performance and cost metrics, model selection, and per-prompt reasoning effort selection.

Creation workflows are chat-led: New Agent and New Skill actions launch a fresh conversation with a seeded creation prompt. The assistant gathers missing requirements (optionally with ask_user), then executes directly with tool-level approvals where configured.

Agents

Autonomous agents with custom roles, system prompts, and model assignments. Agents are created and managed via the chat orchestrator. The agents page provides a read-only browser for viewing agent status and navigating to agent details. Agent detail pages allow editing the assigned model and system prompt.

Settings

Settings persist default model, theme, notification preferences, per-tool approval requirements, context window configuration, and budget limits.

Tool execution approvals are configured per tool in Settings. Tools marked for approval pause execution until approved.

Database Bootstrap

On server startup, AgentStudio now ensures the configured PostgreSQL database exists, installs the required extensions, and applies bundled Drizzle migrations before serving requests. The Postgres role in DATABASE_URL must be allowed to create the target database and install pgcrypto and vector.

If the target database already contains AgentStudio tables or enums but has no recorded Drizzle migrations, startup treats that state as legacy unmanaged schema, wipes the app schemas, and then reapplies the bundled migrations from scratch.

Build note: bun run build skips database bootstrap entirely. DATABASE_URL is only required when the server actually starts.

Tech Stack

• SvelteKit (Svelte 5, TypeScript)
• TailwindCSS v4 + DaisyUI
• PostgreSQL + pgvector
• Drizzle ORM + postgres.js
• OpenRouter SDK
• Playwright E2E
• Adapter Node + Docker (TrueNAS deployment target)

Responsive Breakpoints

AgentStudio now uses a canonical three-tier responsive system:

• mobile: default styles below 48rem (768px)
• tablet: tablet: utilities at 48rem and above
• desktop: desktop: utilities at 80rem (1280px) and above

Implementation details:

• The canonical tokens are defined in src/routes/layout.css via Tailwind v4 @theme breakpoint variables.
• Legacy aliases (sm, md, lg, xl) are mapped to these tiers for compatibility, but new work should prefer tablet: and desktop: utilities.

Getting Started

1. Install dependencies:

bun install

2. Copy environment variables:

cp .env.example .env

3. Update .env values for your services:

• DATABASE_URL
• OPENROUTER_API_KEY
• SEARXNG_URL and SEARXNG_PASSWORD
• SANDBOX_WORKSPACE (base root for per-user workspaces; defaults to /workspace/users)
• VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY
• ORIGIN
• GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET, APP_ENCRYPTION_KEY (only needed if connecting GitHub at /source-control for repo sync, clone, push, and PR creation)
• GITHUB_WEBHOOK_SECRET (only needed to ingest pull_request / check_run events at POST /api/webhooks/github; missing → endpoint returns 503)
• AZURE_DEVOPS_OAUTH_CLIENT_ID, AZURE_DEVOPS_OAUTH_CLIENT_SECRET (only needed if connecting Azure DevOps at /source-control)
• AZURE_DEVOPS_OAUTH_CALLBACK_URL (optional override; only set when running behind a reverse proxy where ORIGIN does not match the externally-reachable callback URL)

Database note:

• DATABASE_URL should point at the final application database name even if that database does not exist yet.
• The configured Postgres role must be able to create that database on first start and run CREATE EXTENSION IF NOT EXISTS pgcrypto and CREATE EXTENSION IF NOT EXISTS vector.
• A database with existing AgentStudio schema objects but no Drizzle migration history will be reset on startup before migrations are applied.
• To force a clean rebuild of a development database, run bun run db:reset — drops the target database and reruns the same ensure-exists → migrate → seed bootstrap the server runs at boot.

4. Run the app:

bun run dev

5. Run checks/tests:

bun run check
bun run test:e2e

Playwright E2E policy:

• bun run test:e2e runs with real external integrations (OpenRouter, SearXNG, sandbox tools).
• Required env vars for E2E: DATABASE_URL, AUTH_PASSWORD, OPENROUTER_API_KEY, SEARXNG_URL, SANDBOX_WORKSPACE.
• The suite fails fast during global setup if any required dependency is missing or unreachable.

Native Release Builds

• GitHub Releases now trigger a workflow that builds native artifacts and attaches them to the release.
• If repository secret TAURI_REMOTE_URL is set, native builds open that hosted URL in the Tauri webview instead of bundled frontend assets. This is the intended mode for thin-shell desktop/mobile releases backed by the Docker-hosted Node app.
• Outputs:
  • Windows installer .exe
  • Android .apk
• Workflow file: .github/workflows/release-native-builds.yml
• Trigger: publish a GitHub Release (tag-based release flow)
• Icon source-of-truth: static/icon.svg.
• Generated platform icon files under src-tauri/icons are recreated automatically by bun run tauri:icons in CI and before Tauri dev/build.

Local Android Commands (Windows)

• bun run android:build:local builds a debug APK using the known-good local SDK/NDK + MSVC setup and TAURI_REMOTE_URL=https://agentstudio.derekhearst.com.
• bun run android:install:local installs the latest built APK to a connected device and launches the app.
• bun run android:run:local builds, installs, and launches in one command.

Optional script args:

• Build with a different URL: powershell -ExecutionPolicy Bypass -File scripts/android-build-local.ps1 -RemoteUrl "https://your-host"
• Install a specific APK file: powershell -ExecutionPolicy Bypass -File scripts/android-install-local.ps1 -ApkPath "path\\to\\app.apk"

Notes:

• bun run test:e2e is the primary CI path and uses real integrations.
• Provider auth errors (for example User not found) indicate credential/account issues rather than app test harness issues.

Docs

• Master implementation order: docs/structure/implementation-order.md
• Architecture refactor plan: docs/structure/plan.md
• Runtime spec: docs/runtime/spec.md
• Chat plan: docs/chat/plan.md
• Memory spec: docs/memory/spec.md
• UI spec: docs/ui/spec.md
• Operations spec: docs/operations/spec.md

Projects

Projects are durable containers for the work users produce with their agents — named artifacts with append-only version history. Each edit creates a new immutable version, rollback is non-destructive (creates a new version with the older content). Browse at /projects. Agents can read/create/edit artifacts via the projects capability group when a project-related query auto-suggests it. See docs/projects/projects.md for the user-facing domain doc, docs/projects/spec.md for the full data model + behavior contracts, or docs/projects/plan.md for the phased build sequence.

Memory Palace

AgentStudio includes an in-house port of MemPalace for long-term memory. Conversations are auto-mined into a Wing → Room → Closet → Drawer hierarchy with vector + tsvector + temporal hybrid recall, and recalled drawers are injected as a <memory_context> system block before each user turn. Configurable from Settings → Memory Palace, browsable at /memory. See docs/memory/memory.md for the user-facing domain doc, docs/memory/spec.md for the full pipeline + schema, or docs/memory/plan.md for the build sequence + bench harness.

A LongMemEval evaluation harness mirrors the upstream methodology:

bun run bench:longmemeval:download
bun run bench:longmemeval:smoke --dataset=oracle --limit=5

Architecture Conventions

• Domain-first API boundaries: browser-consumed remote functions live in src/lib/{domain}.
• Server-only internals are colocated in domain folders under src/lib/** and are only imported by remote functions or +server routes.
• Route and component imports should prefer domain barrels (for example, $lib/chat, $lib/agents) over deep *.remote paths.

Auth and Users

• Authentication uses WebAuthn passkeys (no OAuth or password login).
• Native mobile/desktop webviews that do not expose WebAuthn now show an Open in browser to sign in fallback on the login page.
• On first startup, the server seeds an unclaimed admin account and logs a one-time bootstrap claim URL/key.
• Admins create new accounts from /users.
• Accounts are claimed by the first successful passkey registration for that username.
• User removal is soft-delete; access is blocked while historical data remains owned by that user.

Route Map

• / Redirects to chat
• /login Authentication
• /users Admin user management
• /chat Conversations
• /chat/[id] Chat detail
• /cost Cost dashboard
• /agents Agent management
• /automations Scheduled automation workflows
• /observability/logs Server-side log viewer (warn/error events, filterable, mobile-friendly)
• /settings App configuration