Agentic Smith
English | 简体中文 | 日本語
Agentic Smith is a self-hosted AI agent for persistent teammates, maintained by Jerith AI.
It runs on the web, as an Electron desktop app, and as an Expo mobile client. Bring your own
model and computer provider, or run the complete stack locally.
Agentic Smith is a new fork under active development. Learn more at jerithai.com.
Features
- Persistent bots with their own conversations, memory, routines, and history
- Voice mode: speak replies, dictate, and call a bot. Bring your own ElevenLabs, OpenAI, Cartesia, or Fish Audio key, or use a Mac server's installed voices
- Shared Team Computers and isolated Private computers
- Browser, terminal, file, and graphical desktop access
- Bots that can delegate to peer bots or short-lived subagents
- Bring-your-own model credentials through Pi
- App integrations through Composio or Pipedream Connect, plus user-installed Treg, remote MCP, and OpenAPI tool sources
- Docker, E2B, Daytona, CreateOS, Boat, and trusted local-computer support
Stack
- TypeScript
- React 19, Vite, and Tailwind CSS
- Electron and Expo
- Hono and oRPC
- PostgreSQL and Prisma
- Better Auth
- Graphile Worker
- Pi
- Docker, E2B, Daytona, CreateOS, and Boat
- Composio, Pipedream Connect, MCP, and OpenAPI integrations
Status
This fork does not publish container images yet. Build from a source checkout with the
instructions below; the upstream image tags are intentionally not used.
Run on a server
Bots stay on when the backend runs on a server. Use the same installer on a VPS, then connect from
the desktop app, the mobile app, or a browser.
bash install-images.sh --prepare-only
# edit .env: SANDBOX_PROVIDER=boat (or e2b / daytona / createos) with its API key, AGENTIC_SMITH_HOST=your.domain
bash install-images.sh
Put HTTPS in front of port 5173; docs/self-host-production.md
covers the Caddy setup and host hardening. In the desktop app choose Existing instance and enter
the https:// address.
Local development (source checkout)
You need Node.js 22.22.2 or newer in the 22.x line, Node.js 24.x, or Node.js 26+;
pnpm 12; and Docker. Node.js 23.x and 25.x are not supported.
git clone https://github.com/ParadoxFuzzle/agentic-smith.git
cd agentic-smith
cp .env.example .env
Set POSTGRES_PASSWORD and POSTGRES_APP_PASSWORD to two values from openssl rand -hex 16,
then put them in DATABASE_MIGRATION_URL and DATABASE_URL. The app connects as its own
agentic_smith_app login, which row-level security applies to; migrations run as the owner
(database roles). Set BETTER_AUTH_SECRET, ENCRYPTION_KEY, and SCREEN_PROXY_SECRET to
independent long random values. Docker sandboxes also need a dedicated
SANDBOX_SUPERVISOR_TOKEN. You can also set OPENROUTER_API_KEY, or connect a supported
model provider during onboarding.
For host-side development with Docker Desktop, set SANDBOX_CONTROL_VIA_LOOPBACK=true
in .env. The supervisor discovers Docker Desktop's user socket automatically;
DOCKER_HOST or DOCKER_SOCKET can override it for another Docker runtime.
Managed app catalogs are optional. Set COMPOSIO_API_KEY for Composio, or the
PIPEDREAM_CLIENT_ID, PIPEDREAM_CLIENT_SECRET, and PIPEDREAM_PROJECT_ID trio for Pipedream
Connect. Users can add an HTTPS MCP server, Treg endpoint, or OpenAPI JSON document from
Integrations without enabling either managed catalog. Connector credentials are encrypted on the
server and are never returned by the API.
Treg is usage-metered. Self-hosters supply their own Treg token; operators embedding Treg in a
hosted product should review Treg's integration terms, which require
a written agreement for hosted resale.
pnpm install
pnpm sandbox:build
pnpm dev
pnpm dev uses the Postgres in DATABASE_URL when it accepts a connection. Otherwise it starts a
local agentic-smith-dev-postgres container with Docker, and every checkout reuses that one. It applies
migrations and generates the Prisma client before starting. A branch that adds migrations main
doesn't have gets its own database on the same server, copied from the shared one when possible,
so unmerged schema changes stay out of it. When the default ports are taken, for example by
another git worktree, it moves to the next free block and prints the URL. Set WEB_PORT and
API_PORT to choose ports yourself.
To try a checkout from your phone or another computer, install Tailscale
on each device and set AGENTIC_SMITH_DEV_TAILNET=1 in .env. pnpm dev then serves the web app over
HTTPS at https://<machine>.<tailnet>.ts.net:<web port>, reachable only from devices on your
tailnet, and stops serving it when you quit. Sign in at that URL on every device, including the
one running it. The first run may ask you to turn on HTTPS certificates for your tailnet.
To keep keys in a secrets manager instead of .env, set AGENTIC_SMITH_DEV_RUN_WITH to the command
that runs another with your secrets added, for example op run --env-file=dev.env -- or
infisical run --env=dev --projectId=<project> --. pnpm dev then starts inside it, and the
values it adds win over .env.
To run Postgres from the Compose file instead, start it with the postgres-host overlay, which
publishes loopback 127.0.0.1:5433, and point DATABASE_URL and DATABASE_MIGRATION_URL at it:
docker compose --env-file .env \
-f infra/compose/docker-compose.yml \
-f infra/compose/docker-compose.postgres-host.yml \
up postgres -d
This is the beginning of the README. Read the rest at the original. Read the full README ↗
