Skip to main content
By the end of this guide you’ll have the web and API services running locally, the database migrated, the CLI installed, and a Markdown artifact published to a real URL.

​
Prerequisites

Artifacts is a Bun + Turborepo monorepo. You’ll need a few services available before the first boot.
  • Bun — matches the repository package manager.
  • Node.js 24+ — required to run the apps.
  • PostgreSQL — any Postgres-compatible database, such as Neon.
  • S3-compatible storage — for artifact content, such as Cloudflare R2.
  • Google OAuth credentials — for interactive browser login.

​
1. Install and configure

1

Install dependencies

From the repository root:
bun install
2

Create your environment file

cp .env.example .env
At minimum, align the browser-visible app origin and the internal API origin:
BETTER_AUTH_URL="http://localhost:3000"
PUBLIC_APP_URL="http://localhost:3000"
INTERNAL_API_URL="http://127.0.0.1:3001"
The Next.js app rewrites /api/*, /mcp, and OAuth metadata routes to the Hono API, so browser cookies stay scoped to the public web origin. See Configuration for every variable.
3

Run database migrations

Apply migrations before the first boot:
bun run db:migrate
When you change schema definitions later, regenerate migrations with bun run db:generate.

​
2. Start the app

Run the web and API apps together through Turbo: 
bun run dev
ServiceURL
Web apphttp://localhost:3000
APIhttp://127.0.0.1:3001
MCP endpoint (via web origin)http://localhost:3000/mcp
API health checkhttp://127.0.0.1:3001/health

​
3. Install the CLI

Build the TypeScript CLI and put the artifacts command on your PATH: 
bun run cli:build
bun run cli:install
Prefer not to install globally? Run it straight from the repo root instead: 
node apps/cli/dist/cli.js <command>

​
4. Log in

Point the CLI at your local services, then start browser login: 
export AGENT_ARTIFACTS_BASE_URL="http://127.0.0.1:3001"
export AGENT_ARTIFACTS_WEB_URL="http://localhost:3000"

artifacts login
artifacts whoami
Credentials are saved to ~/.config/agent-artifacts/credentials.json with mode 0600.

​
5. Claim a username

Your personal workspace slug comes from your username. If you haven’t claimed one yet: 
artifacts profile set-username --username alice

​
6. Publish your first artifact

1

Create a project

artifacts project create --json '{"ownerUsername":"alice","slug":"default","title":"Default"}'
2

Write a Markdown file

printf '# Launch review\n\nA durable artifact from the CLI.\n' > launch-review.md
3

Publish it

artifacts push --owner alice --project-slug default --file ./launch-review.md
push infers the type, title, and slug from the file. Override them with --type, --title, and --slug.
The command returns the artifact’s URL. Open it in the browser to see your published Markdown.

​
Next steps

Learn the artifact model

Versions, content types, and how storage works.

Share and control access

Public, private, email allowlists, and share links.

CLI reference

Every command, flag, and environment variable.

Connect an MCP client

Give agents structured artifact tools over MCP.