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

# Creating Projects

> Three paths to a new OpenSail project: pick a template, import a git repo, or describe what you want and let the agent scaffold it.

<img src="https://mintcdn.com/tesslate/VT6tbZolrCfpx26M/images/opensail-banner.png?fit=max&auto=format&n=VT6tbZolrCfpx26M&q=85&s=66579c47537b3464fb65b229cc9ab0fd" alt="Tesslate OpenSail" width="4712" height="1612" data-path="images/opensail-banner.png" />

## Three ways to start

OpenSail gives you three entry points. Pick the one that matches how you are starting.

<CardGroup cols={3}>
  <Card title="Template" icon="file-code">
    Marketplace base with working code, containers, and config.
  </Card>

  <Card title="Import" icon="code-branch">
    GitHub, GitLab, or Bitbucket repo, including private with OAuth.
  </Card>

  <Card title="Describe" icon="wand-magic-sparkles">
    Natural language. The agent scaffolds the project for you.
  </Card>
</CardGroup>

All three run through the same `POST /api/projects` endpoint. A background task sets up the directory, seeds the workspace, and the frontend polls `GET /api/tasks/{task_id}` for progress. When the task completes, you land in the project builder.

## Method 1: From a template

The marketplace ships dozens of bases covering every popular framework. Pick one and you get working code, pre-wired containers, and a valid `.tesslate/config.json`.

<Steps>
  <Step title="Open the dashboard">
    Navigate to `/dashboard` and click **Create Project** or use the create button on `/home`.
  </Step>

  <Step title="Pick a template">
    The wizard shows the featured bases. Browse all of them from the marketplace browse route. Common picks:

    * **Next.js 16** for full-stack React with App Router
    * **Vite + FastAPI** for React frontend + Python API
    * **Expo** for React Native mobile
    * **Go API** for Go backends
    * **Full-stack CRM** for multi-container starters
  </Step>

  <Step title="Name and create">
    Pick a project name. The slug auto-generates (`my-app-k3x8n2`). Create submits the request and the background task begins.
  </Step>

  <Step title="Wait for setup">
    The task clones the base repo, seeds the volume, and registers containers. Progress: 5% directory created, 10-90% clone and file sync, 100% done.
  </Step>

  <Step title="Land in the builder">
    The frontend navigates to `/project/{slug}/builder` when setup completes. Containers are stopped; click Start to boot them.
  </Step>
</Steps>

<Info>
  Templates are just `MarketplaceAgent` rows with `item_type='base'` and a `git_repo_url`. Publishing your own base is covered in the marketplace docs.
</Info>

## Method 2: Import from git

OpenSail supports GitHub, GitLab, and Bitbucket, including private repos via OAuth.

<Steps>
  <Step title="Connect your provider (first time only)">
    The first import prompts OAuth with your git provider. Tokens are stored encrypted in `DeploymentCredential` and reused for future imports, push, pull, and commit.
  </Step>

  <Step title="Pick a repo">
    The import modal lists your accessible repos (pulled from the provider's API). Filter by owner, search by name. Private repos are listed alongside public ones.
  </Step>

  <Step title="Select a branch">
    Default branch is pre-selected. Override for feature branches or forks.
  </Step>

  <Step title="Create">
    Submit. The background task clones the repo, seeds the workspace, and runs the Librarian agent against the tree to generate `.tesslate/config.json`.
  </Step>

  <Step title="Review the generated config">
    The setup wizard opens at `/project/{slug}/setup`. The Agent tab shows the LLM-generated graph; the Manual tab lets you hand-edit the same `ServiceConfigForm`. Confirm to save.
  </Step>
</Steps>

<Info>
  Deep-link imports work too. An external "Edit in OpenSail" button can link to `/import?repo=https://github.com/user/repo`. The auth-aware redirect sends signed-in users to the import flow and unauthenticated users to login while preserving the destination.
</Info>

### Supported providers

| Provider      | OAuth | Private repos | Push/pull |
| ------------- | ----- | ------------- | --------- |
| **GitHub**    | Yes   | Yes           | Yes       |
| **GitLab**    | Yes   | Yes           | Yes       |
| **Bitbucket** | Yes   | Yes           | Yes       |

## Method 3: Describe what you want

The "describe" flow gives the agent a blank workspace and your prompt. The agent picks an appropriate base, adjusts it, and iterates until the scaffold matches your description.

<Steps>
  <Step title="Open the describe flow">
    From the dashboard, click **Describe your app** (or use the command palette).
  </Step>

  <Step title="Write your prompt">
    Be specific. "A Slack-style team chat app with channels, DMs, and search, built with Next.js and Postgres" gives the agent enough to scaffold. "An app" does not.
  </Step>

  <Step title="Pick compute tier">
    If you are on Kubernetes, choose the compute tier. Tier 0 scaffolds without a compute pod; tier 1 or 2 boot containers so the preview works immediately.
  </Step>

  <Step title="Let the agent scaffold">
    The agent picks a base, runs `apply_setup_config` to wire containers, installs dependencies, and writes an initial implementation. You watch progress in the chat panel.
  </Step>

  <Step title="Iterate">
    When the agent stops, the preview is live. Ask for changes, review diffs, approve or reject.
  </Step>
</Steps>

<Info>
  The describe flow uses the same agent loop as any chat session. Progressive persistence means you can close the tab, grab coffee, and come back to a finished scaffold.
</Info>

## What happens under the hood

All three methods produce the same end state: a `Project` row, a provisioned volume, container records, and a valid `.tesslate/config.json`.

<Steps>
  <Step title="POST /api/projects">
    Creates the Project row with status `creating`, assigns a unique slug, kicks off the background task, returns the project and a `task_id`.
  </Step>

  <Step title="_perform_project_setup">
    Runs in the background. Creates the directory (Docker) or allocates the volume (K8s). Clones the source (base or git). Writes files to the volume.
  </Step>

  <Step title="Config resolution">
    Reads `.tesslate/config.json` from disk. If absent, falls back to LLM analysis (Librarian agent), then to a minimal single-app fallback.
  </Step>

  <Step title="Container sync">
    Upserts Container rows from the config. Creates ContainerConnection, DeploymentTarget, and BrowserPreview records as declared.
  </Step>

  <Step title="Task complete">
    The frontend poll flips to 100%. Navigation to `/project/{slug}/builder`. Containers are stopped and ready to start.
  </Step>
</Steps>

## Compute tier selection

On Kubernetes projects, you can pick a compute tier at creation time:

<Tabs>
  <Tab title="None">
    No compute provisioning. The workspace exists, but nothing runs. Use when you just want source code and will run locally.
  </Tab>

  <Tab title="Ephemeral">
    Tier 1 warm ephemeral pool. Shell and quick operations work; long-running dev servers do not. Cheap, fast.
  </Tab>

  <Tab title="Environment">
    Full Tier 2 namespace with live preview, persistent dev servers, and hibernation. What you want for active development.
  </Tab>
</Tabs>

You can upgrade or downgrade later from the Project Overview page.

## After creation

Once the project is ready, the usual surfaces are available:

<CardGroup cols={2}>
  <Card title="Code editor" icon="code" href="/guides/code-editor">
    Monaco with the project file tree.
  </Card>

  <Card title="Live preview" icon="eye" href="/guides/live-preview">
    Iframe with hot module reload.
  </Card>

  <Card title="Architecture Panel" icon="diagram-project" href="/guides/architecture-panel">
    Visual graph editor for the config.
  </Card>

  <Card title="Chat interface" icon="comments" href="/guides/chat-interface">
    Talk to agents about your project.
  </Card>
</CardGroup>