adam

Filesystem-first framework for durable AI agents — VPS / self-host only.

Author an agent as a directory on disk — instructions, skills, tools, channels, and schedules — then build and run it as a long-lived Node process (local, shipnode, or Docker Compose).

Vercel is not a supported host. No Vercel Sandbox, no adam link / Vercel deploy, no .vercel/output production path. Deploy with shipnode or Compose.

Apache-2.0 sources derived from an upstream agent framework; see LICENSE and NOTICE.

Agent layout

my-agent/
└── agent/
    ├── agent.ts            # Optional: model and runtime config
    ├── instructions.md     # Required: system prompt
    ├── tools/              # Optional: typed model tools
    ├── skills/             # Optional: on-demand procedures
    ├── channels/           # Optional: HTTP, Slack, Discord, …
    └── schedules/          # Optional: cron jobs

Quick start

pnpm install
pnpm build
# scaffold / run via the adam CLI after build:
# npx adam init my-agent
# cd my-agent && pnpm dev

Production-style loop:

adam build
adam start --host 0.0.0.0 --port 3000
curl -sS http://127.0.0.1:3000/adam/v1/health

For self-host / VPS deploys, do not set VERCEL. Prefer a direct provider API key (e.g. OPENAI_API_KEY) and pin a non-platform sandbox (docker() or justbash()).

Monorepo

Path	Purpose
packages/adam	Framework + adam CLI
packages/adam-catalog	Internal catalog helpers
apps/	Docs, fixtures, framework examples
docs/	User documentation
e2e/	End-to-end eval fixtures

Commands

pnpm install
pnpm build
pnpm test:unit
pnpm test:integration
pnpm typecheck

License

Apache-2.0. See LICENSE and NOTICE.

Deploy on a VPS (shipnode)

Uses your local shipnode package (@devalade/shipnode via file:../shipnode).

pnpm install
cp .env.vps.example .env.vps   # set OPENAI_API_KEY, ADAM_VPS=1, …

export SHIPNODE_HOST=1.2.3.4
export SHIPNODE_DOMAIN=agent.example.com

pnpm shipnode:setup            # once per server
pnpm shipnode:env
pnpm shipnode:deploy

Config: shipnode.config.ts · Agent: deploy/vps/example-agent

Day-to-day: pnpm shipnode:status · pnpm shipnode:logs · pnpm shipnode:rollback

Docker Compose alternative: pnpm vps:up (see deploy guide).

Self-host rules: ADAM_VPS=1, no VERCEL, direct provider keys; example agent pins justbash().