Use Docker and prepare a custom runtime

Use a hosted workspace when your project needs Docker, native dependencies, or a custom server. Free Browser workspaces cannot build or run containers. This guide helps you verify a container in development and prepare the separate production setup.

Start with a small container check

In a hosted project, open Advanced → Session menu → Terminal, or ask the agent to run the commands. On a phone, the code icon opens Advanced. Run docker info first to confirm Docker is available; if it fails, keep the error and follow Troubleshooting.

For a small example, create server.mjs in a new project folder:

import { createServer } from "node:http";

const server = createServer((request, response) => {
  response.writeHead(200, { "Content-Type": "application/json" });
  response.end(JSON.stringify({ ok: true, path: request.url }));
});

server.listen(Number(process.env.PORT || 3000), "0.0.0.0");
process.on("SIGTERM", () => server.close(() => process.exit(0)));

Create a Dockerfile beside it:

FROM node:22-alpine
WORKDIR /app
COPY --chown=node:node server.mjs ./
USER node
ENV PORT=3000
EXPOSE 3000
CMD ["node", "server.mjs"]

Build and run from that folder:

docker build -t rigless-runtime-example .
docker run --rm -p 8080:3000 rigless-runtime-example

Keep that command running. In another terminal, run curl http://127.0.0.1:8080/health. Expect {"ok":true,"path":"/health"}. Open the hosted preview for port 8080 to check browser access too. Press Ctrl+C in the container's terminal when finished.

This checks image construction, startup, port mapping, and an HTTP response. Your actual application still needs its own functional checks.

Make your project's setup reproducible

Keep runtime versions, dependency manifests, lockfiles, and startup instructions in the repository. For larger images, a multi-stage build can leave compilers and development dependencies out of the final image. Use a .dockerignore to exclude caches, local output, and credentials from the build context.

A web process should stay in the foreground, listen on 0.0.0.0, use the configured port, and write useful output to standard output and standard error. Provide a health path that returns a successful response when the application is ready.

Prepare publishing separately

Rigless publishing uses a verified project root, build command, start command, port, and health path. A Dockerfile alone does not configure those values or prove that an image built in your development workspace will be present in the separate release environment.

Ask the agent to inspect how the application can be rebuilt and started from its source:

Prepare this project for Rigless publishing. Identify and verify the project
root, production build command, start command, port, and health path.
If the setup uses Docker, account for rebuilding or loading the image in the
release environment. Do not rely on an image cached only in this workspace.
Report any dependency or deployment requirement you cannot verify.

Resolve those requirements before using Publish an app. Rigless verifies an HTTP application; a Docker Compose stack with several independently managed services needs additional design and verification.

Keep application data portable

Record where the app stores customer data, uploads, and configuration. A workspace archive does not export running containers, Docker volumes, or an external database. Use the relevant service's backup and restore process for that data.

When moving to another host, take the source and build instructions, configure the new environment, move required data, and test the result. The export guide covers that handoff.