> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Info>
  Artifacts is a Bun + Turborepo monorepo. You'll need a few services available before the first boot.
</Info>

* **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

<Steps>
  <Step title="Install dependencies">
    From the repository root:

    ```bash theme={"theme":"github-dark"}
    bun install
    ```
  </Step>

  <Step title="Create your environment file">
    ```bash theme={"theme":"github-dark"}
    cp .env.example .env
    ```

    At minimum, align the browser-visible app origin and the internal API origin:

    ```bash theme={"theme":"github-dark"}
    BETTER_AUTH_URL="http://localhost:3000"
    PUBLIC_APP_URL="http://localhost:3000"
    INTERNAL_API_URL="http://127.0.0.1:3001"
    ```

    <Tip>
      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](/reference/configuration) for every variable.
    </Tip>
  </Step>

  <Step title="Run database migrations">
    Apply migrations before the first boot:

    ```bash theme={"theme":"github-dark"}
    bun run db:migrate
    ```

    When you change schema definitions later, regenerate migrations with `bun run db:generate`.
  </Step>
</Steps>

## 2. Start the app

Run the web and API apps together through Turbo:

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
bun run cli:build
bun run cli:install
```

Prefer not to install globally? Run it straight from the repo root instead:

```bash theme={"theme":"github-dark"}
node apps/cli/dist/cli.js <command>
```

## 4. Log in

Point the CLI at your local services, then start browser login:

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
artifacts profile set-username --username alice
```

## 6. Publish your first artifact

<Steps>
  <Step title="Create a project">
    ```bash theme={"theme":"github-dark"}
    artifacts project create --json '{"ownerUsername":"alice","slug":"default","title":"Default"}'
    ```
  </Step>

  <Step title="Write a Markdown file">
    ```bash theme={"theme":"github-dark"}
    printf '# Launch review\n\nA durable artifact from the CLI.\n' > launch-review.md
    ```
  </Step>

  <Step title="Publish it">
    ```bash theme={"theme":"github-dark"}
    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`.
  </Step>
</Steps>

The command returns the artifact's URL. Open it in the browser to see your published Markdown.

## Next steps

<CardGroup cols={2}>
  <Card title="Learn the artifact model" icon="box" href="/concepts/artifacts">
    Versions, content types, and how storage works.
  </Card>

  <Card title="Share and control access" icon="lock" href="/guides/sharing-and-permissions">
    Public, private, email allowlists, and share links.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command, flag, and environment variable.
  </Card>

  <Card title="Connect an MCP client" icon="plug" href="/surfaces/mcp">
    Give agents structured artifact tools over MCP.
  </Card>
</CardGroup>