Quickstart

Run Artifacts locally, then publish your first artifact from the CLI.

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

Service	URL
Web app	http://localhost:3000
API	http://127.0.0.1:3001
MCP endpoint (via web origin)	http://localhost:3000/mcp
API health check	http://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.