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.
An API key for one provider, see 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. 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 adds a database to the backend.
Ports and LAN access explains opening the frontend to another device.

Source as Markdown: /docs/tutorials/frontend-and-backend.md · Updated 2026-10-11 · Was this right? Tell us

A frontend and a backend as connected projects