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

# Getting started

> Set up your environment and create a BRICKS project

## Prerequisites

* [Bun](https://bun.sh) v1.3 or later
* [Git](https://git-scm.com) (strongly recommended)
* A [BRICKS](https://bricks.tools) workspace account

## Create a project

There are three ways to get a BRICKS project.

### Option 1: BRICKS Controller (recommended)

Generate a project from the [BRICKS Controller](/controller/applications) web interface:

1. Open your application in BRICKS Controller
2. Click **Generate Project**
3. Configure options:
   * **AGENTS.md** — AI agent instructions (for Claude Code, Codex, etc.)
   * **CLAUDE.md** — Claude Code-specific instructions
   * **GEMINI.md** — Gemini CLI instructions
   * **GitHub Actions** — CI/CD deployment workflows
4. Click **Download Project (.zip)**

See the [BRICKS Controller docs](/controller) for workspace setup, Foundation binding, and application management.

Extract the archive and run:

```bash theme={null}
cd my-app
bun install
```

### Option 2: CLI

Install the BRICKS CLI and initialize from the command line:

```bash theme={null}
bun add -g @fugood/bricks-cli
bricks auth login
bricks app project-init <application-id> --yes
```

The `project-init` command generates the project files and installs dependencies. You can customize the output with flags:

| Flag                  | Description                   |
| --------------------- | ----------------------------- |
| `--no-agents`         | Skip AGENTS.md generation     |
| `--no-claude`         | Skip CLAUDE.md generation     |
| `--gemini`            | Include GEMINI.md             |
| `--no-github-actions` | Skip GitHub Actions workflows |

### Option 3: CTOR

Use [CTOR](/ctor) — a desktop IDE with an integrated AI agent that can create, edit, and deploy projects through chat.

## Development workflow

### Compile

Type-check and compile your TypeScript into the JSON configuration the BRICKS runtime uses:

```bash theme={null}
bun compile
```

### Preview

Launch a local preview to test your app:

```bash theme={null}
bun preview
```

The preview opens your app in a local window. Use `--show-menu` for additional testing options.

### Deploy

Deploy your compiled app to the [BRICKS](https://bricks.tools) server:

```bash theme={null}
bun deploy-app
```

| Flag                       | Description                                   |
| -------------------------- | --------------------------------------------- |
| `--changelogs <text>`      | Changelogs text for the release               |
| `--changelogs-file <path>` | Read changelogs from a file                   |
| `--auto-commit`            | Auto-commit unstaged changes before deploying |
| `--auto-version`           | Auto-bump patch version before deploying      |
| `--version <version>`      | Set explicit version for the release          |
| `-y, --yes`                | Skip all prompts                              |

Version resolution priority: `--version` flag > `--auto-version` bump > `package.json` version. Both `--version` and `--auto-version` update `package.json` before deploying.

<Warning>
  Deployment requires a clean Git working tree. Commit your changes before deploying, or use `--auto-commit` to commit automatically.
</Warning>

### Pull

Pull the latest version of your application from the server:

```bash theme={null}
bun pull-app
```

This syncs your local project with the server version. Use `--force` to overwrite local changes.

## AI-assisted development

bricks-ctor is designed to work with AI coding agents. When you generate a project with AI instructions enabled, the following files are created:

| File        | Used by                 |
| ----------- | ----------------------- |
| `CLAUDE.md` | Claude Code, CTOR       |
| `AGENTS.md` | Codex CLI, other agents |
| `GEMINI.md` | Gemini CLI              |

These files contain project-specific instructions, architecture patterns, and BRICKS domain knowledge that help AI agents understand and modify your application.

The project also includes a [built-in MCP server](/ctor-pkg/mcp-server) and a [built-in skill](/ctor-pkg/skills) that provide tools and domain knowledge for AI agents working with your project.

<Tip>
  Use [CTOR](/ctor) for a fully integrated experience with AI agent chat, deployment, and preview — all in one app.
</Tip>

## CI/CD with GitHub Actions

If you enabled GitHub Actions during project generation, your repository includes workflows for automated deployment. Push to your main branch to trigger a deploy.