# A frontend and a backend as connected projects

Run a frontend and a backend as two Borago Board projects, connect them, and let the frontend's container reach the backend by name on a private network.

Every project in Borago Board runs its container on a network of its own, so one project cannot reach another unless you connect them. A project created on an older version joins its own network when its container is next recreated. A frontend and a backend kept as two projects need exactly one exception. This tutorial creates both, connects them, and has the frontend's development server forward its API calls to the backend by name.

## You will build

Two projects, Backend API and Web Frontend. The backend serves a small JSON endpoint. The frontend shows it in a page you open on this computer. The two containers share a private network that nothing else on the machine is on.

## You need

- The desktop app with Docker running, see [Installing Docker with the app](/docs/guides/installing-docker/).
- An API key for one provider, see [Choosing an AI provider](/docs/guides/choosing-an-ai-provider/).
- Host ports 8000 and 5173 free on this computer. Any free pair works if you change the numbers throughout.

## Steps

### 1. Create the backend project

Press **Add project** and name it `Backend API`. Set **Local path** to an empty folder, so the code is kept on your disk. In the desktop app, **Browse** can create one. Walk the other tabs as in [Creating a project](/docs/guides/creating-a-project/). On **Ports**, press **+ Add port** and set **Host** to 8000 and **Container** to 8000. Leave **Expose to LAN** off. Finish with **Create project** and **Start container**.

What happens. The published port is bound to this computer only, so you can test the API in a browser here and no other device can reach it. The connection in step 3 does not use this port.

### 2. Create the frontend project

Do the same for `Web Frontend`, with its own empty folder and **Host** 5173 and **Container** 5173 on **Ports**.

What happens. Each new container starts on its own network. On the Containers tab, **Dev container name** shows the generated name, the project name in kebab case followed by `-borago-board`.

### 3. Connect the two projects

With Web Frontend selected, press **Edit project** and open the **Containers** tab. Under **Connected projects**, choose **Backend API** from **Connect a project**. It appears as a chip. Press **Save changes**.

What happens. The connection is symmetric, so Backend API now lists Web Frontend too, and it syncs to your other devices. The app creates a small network for this pair only. Connecting A to B and B to C does not connect A to C.

### 4. Restart both containers

Saving offers **Restart the container?**. Press **Restart now**. Then select Backend API in the project picker and press **Restart container** among its project controls.

What happens. A container joins a network only when it is created, so both sides need a restart. A restart recreates the container. Code in the local path is untouched.

### 5. Know the names

From the frontend's container the backend answers to `backend-api`, and also to its container name, `backend-api-borago-board`. The backend reaches the frontend as `web-frontend`. Use the port the server listens on inside its container, here 8000.

What happens. Each side gets a fixed address on the pair network and an entry for the other project under those two names. Every run in a connected project knows which projects it can reach and by which names.

### 6. Write the backend task

Select Backend API, press **Add task** in **Planning**, and paste:

```
Create a small HTTP API in this repository. It must listen on 0.0.0.0 port
8000 inside the container, so the connected Web Frontend project can reach
it at http://backend-api:8000. Add GET /api/health returning
{"status": "ok"} as JSON. Add a test for the endpoint, and write the command
that starts the server in README.md.
```

Press **Add task** and drag the card to **To Do**. Wait for **Done**.

### 7. Start the backend

Press **Terminal** among Backend API's project controls and run the start command from its README. Leave the terminal open.

What happens. The terminal is a shell in the backend's container. Its session keeps running when you close the terminal window, until you end it or the app closes.

### 8. Write the frontend task

Task mentions work inside one project only, so a task here cannot name the backend's task or wait for it. The description carries the agreement instead, and you start this task after the backend one is done. Select Web Frontend, add a task, and paste:

```
Create a small web frontend with a Vite development server listening on
0.0.0.0 port 5173 inside the container. The API lives in the connected
Backend API project at http://backend-api:8000. Configure the dev server to
proxy every request under /api to that address, so the browser only ever
talks to port 5173. Show the result of GET /api/health on the home page.
Before finishing, check with curl from this container that
http://backend-api:8000/api/health answers. Write the command that
starts the dev server in README.md.
```

Move it to **To Do**.

What happens. The browser runs on your computer and cannot resolve `backend-api`. Only the frontend's container can. Proxying through the development server keeps the name on the container side.

## Check it worked

When the frontend task is done, press **Terminal** on Web Frontend and run its start command. Open `http://localhost:5173` on this computer. The page shows the health status from the backend. `http://localhost:8000/api/health` answers directly as well.

## If a name does not answer

The container on the other side is stopped, or has not been restarted since the connection was made. Restart it and check it is running. Then check the server listens on 0.0.0.0 and not only on localhost inside its container.

## Where to go next

- [Let the agent run Postgres beside the project](/docs/tutorials/postgres-beside-the-project/) adds a database to the backend.
- [Ports and LAN access](/docs/guides/ports-and-lan-access/) explains opening the frontend to another device.

Related: [Connected projects](/docs/guides/connected-projects/), [Creating a project](/docs/guides/creating-a-project/), [Container management](/docs/guides/container-management/), [Containers](/docs/reference/containers/)