Repositories

Repositories are the foundation of every ReArch conversation. Connect your organization’s repositories so that any team member can start an AI-powered coding session against real code — no local setup required.

ReArch supports two integration approaches: templates for zero-effort onboarding, and a custom .rearch/ folder for full control over the development environment. You can start with a template and adopt a custom configuration later as your needs grow.

Connecting a Git Provider

Before importing repositories, connect ReArch to your git provider. This is a one-time setup per workspace.

1. Navigate to Resources > New.
2. Select your provider (e.g., Bitbucket).
3. Fill in the connection details:

Field	Description
Name	A display name for this connection.
Workspace	The Bitbucket workspace slug.
Email	The Atlassian account email used for API authentication.
Clone Username	The Bitbucket username used for HTTPS clone operations.
API Token	An Atlassian API token. ReArch uses this for API calls and git push operations inside containers.

4. Save the resource. ReArch validates the credentials against the provider API before saving.

Once connected, the resource appears in your Resources list and you can import repositories from it.

Importing Repositories

After connecting a git provider, import the specific repositories your team will work with.

1. Open the resource you created and navigate to Repositories.
2. Click Import to open the import dialog.
3. Search for a repository by name. ReArch queries the provider API and displays matching results.
4. Select a repository and confirm the import.

ReArch fetches the repository metadata — branches, recent commits, and clone URLs — and creates a sub-resource entry. The repository is now available for configuration but is not yet enabled for conversations.

Enabling a Repository

Imported repositories must be explicitly enabled before team members can use them. Open the repository detail page and locate the ReArch Settings card. Toggle Enabled to make the repository available for conversations.

Once enabled, ReArch generates a Start Link — a shareable URL in the format <your-domain>/start#<repository-name>. Anyone on your team can use this link to instantly create a conversation for that repository.

Choosing an Integration Level

ReArch offers two paths for configuring how a repository runs inside a conversation container.

Templates (Minimal Effort)

Templates are built-in environment definitions that require no changes to your repository. Select a template, pick a branch, build the image, and your team can start conversations immediately.

Template	What It Provides
Minimal	VS Code (code-server) and an AI coding agent. The agent can read, modify, and commit code. No application runtime.
Node.js	Everything in Minimal, plus a Node.js runtime that runs your application’s dev server (default: npm run dev on port 3000).
Node.js + Browser	Everything in Node.js, plus Playwright with Chromium. The AI agent can navigate your running application, take screenshots, click elements, and verify changes visually.

Templates are a good fit when:

• You want to get started quickly without modifying your repository.
• Your project is a standard Node.js application with a conventional dev server.
• You do not need databases, custom services, or specialized initialization inside the container.

To use a template, open the repository’s ReArch Settings, select the template from the dropdown, choose the branch to build from, and click Build Docker Image.

Note

When using a template, the repository does not need a .rearch/ folder. ReArch injects the template files automatically during the Docker build.

Custom .rearch/ Folder (Full Control)

For repositories that need databases, custom initialization, multiple services, or any environment beyond what templates provide, create a .rearch/ folder at the root of your repository. This gives you complete control over the container environment.

Select Custom as the template in ReArch Settings when using this approach. ReArch will look for .rearch/Dockerfile in your repository’s configured branch and use it to build the image.

Note

When using a custom configuration, the repository must contain a .rearch/ folder with at least a Dockerfile. The build will fail if the file is not found.

The .rearch/ Folder

The .rearch/ directory contains everything Docker needs to build a self-contained development environment for your project.

Directory Structure

your-repository/
└── .rearch/
    ├── Dockerfile              # Required. Container image definition.
    ├── entrypoint.sh           # Required. Runtime initialization script.
    ├── opencode-package.json   # Optional. Dependencies for AI agent tools.
    └── agent-tools/            # Optional. Custom tools for the AI agent.
        ├── browser.ts
        ├── browser_click.ts
        └── ...

Dockerfile

The Dockerfile defines everything installed in the container. It follows a general structure:

1. System dependencies — supervisor, git, curl, and project-specific packages (e.g., postgresql, redis).
2. Developer tools — code-server (VS Code in the browser), opencode-ai (AI coding agent).
3. User and directory setup — Creates a coder user and the /repository working directory.
4. Repository code — COPY --chown=coder:coder . /repository copies your code into the image.
5. Dependency installation — npm install (or equivalent) so dependencies are baked into the image.
6. Entrypoint — Copies and sets entrypoint.sh as the container entry point.
7. Supervisor configuration — Defines all long-running services with startup priorities.
8. Port exposure — Only ports that users or external services need to reach.

The Dockerfile is always built from the repository root with .rearch/Dockerfile as the build file. This means COPY . /repository includes your entire codebase.

Entrypoint Script

The entrypoint script runs once at container startup, before supervisor takes over. It handles tasks that cannot be done at build time:

Task	Why It Runs at Startup
Git configuration	Uses GIT_TOKEN and email values passed as environment variables at runtime.
Database initialization	The database engine is installed at build time, but creating databases and users requires the engine to be running.
.env file generation	Values depend on runtime environment variables or container-local addresses.
Config patching	Proxy or routing configuration may depend on your application’s specific routes.

The script must end with exec /usr/bin/supervisord ... to hand off process management to supervisor.

Agent Tools (Optional)

The agent-tools/ directory provides the AI agent with custom tools. The most common use case is browser automation via Playwright, which lets the agent:

• Navigate to pages in your running application.
• Take screenshots for visual verification.
• Click elements, fill forms, and interact with the UI.
• Execute JavaScript in the browser context.

To include browser tools, add the agent-tools/ directory and an opencode-package.json that declares the Playwright dependency. Update the DEFAULT_URL in browser.ts to point to your application’s frontend port.

Configuring Container Services

Services define which ports in the container are accessible to users. Each service has a label, an icon, and an internal port number. When a conversation starts, ReArch maps these internal ports to dynamically-assigned host ports and displays them as clickable buttons in the session sidebar.

When using a template, default services are configured automatically:

Template	Default Services
Minimal	Code (port 8080)
Node.js	Code (port 8080), Backend (port 3000)
Node.js + Browser	Code (port 8080), Backend (port 3000)

When using a custom .rearch/ folder, ReArch reads the EXPOSE directives from your Dockerfile and suggests services based on known port conventions (e.g., 8080 for Code, 3000 for Backend, 5173 for Frontend). You can add, remove, or rename services in the ReArch Settings.

Building Docker Images

After configuring a template or adding a .rearch/ folder, build the Docker image so it is ready for conversations.

1. In the repository’s ReArch Settings, select the branch to build from.
2. Click Build Docker Image.
3. ReArch clones the repository, applies the template (if selected), and runs the Docker build. The resulting image is tagged with the branch’s latest commit hash.

You can rebuild at any time to pick up new changes from the branch. ReArch also supports scheduled rebuilds — administrators can configure an automatic rebuild interval from the settings page so that images stay up to date without manual intervention.

Tip

Rebuild the Docker image whenever you make changes to the .rearch/ folder, update dependencies, or want the base image to reflect the latest branch state.

What Each Integration Level Unlocks

The table below summarizes what is available at each integration level.

Capability	Template	Custom .rearch/
VS Code in the browser	Yes	Yes (if configured in Dockerfile)
AI coding agent	Yes	Yes (if configured in Dockerfile)
Git operations (commit, push, PR)	Yes	Yes
Application dev server	Node.js and Node.js + Browser templates	If configured
Live preview of your application	Node.js and Node.js + Browser templates	If configured
Browser automation (screenshots, interaction)	Node.js + Browser template only	If agent tools are included
Database services	No	Yes
Custom initialization logic	No	Yes (via entrypoint)
Custom environment files	No	Yes (via entrypoint)
Multiple custom services	Limited to template defaults	Unlimited
Changes to your repository	None required	Must add .rearch/ folder

Recommended Path

1. Start with the Minimal template to validate the connection and let your team explore AI-powered conversations against your codebase.
2. Move to Node.js when you want the agent to run and test your application inside the container.
3. Move to Node.js + Browser when you want visual verification — the agent takes screenshots to confirm UI changes.
4. Create a custom .rearch/ folder when you need databases, multiple backend services, custom proxy configuration, or any environment that goes beyond what templates offer. Use the built-in templates as a starting reference for your Dockerfile and entrypoint.