Quickstart

Before you start

• A GitHub, GitLab, Bitbucket or Codeberg account, and a repository with a web app, API or static site in it.
• An app that listens on the port in the PORT environment variable. HostStack sets PORT for you; hard-coding 3000 is the most common reason a first deploy fails its health check.

No Dockerfile is needed. HostStack detects Node.js, Bun, Python, Go, Rust, Ruby, PHP, Java, Elixir and .NET and builds them for you. A connected repo with a Dockerfile at its root builds from it instead when you create the service without picking a runtime or commands; an existing service keeps its build until you set a Dockerfile path. See Deploying for how each runtime is detected. For a walk-through of one stack — Next.js, Django, Laravel, Rails, FastAPI, Go or a Node.js server — start from its deploy guide.

Deploy in five steps

1. Create an account

   Sign up at hoststack.dev/register, with an email address or with GitHub. The free tier gives you one Nano service and one Starter Postgres without a card.

2. Create a project

   A project groups the services and databases that make up one app, and gives them a private network to talk to each other on. In the dashboard, click New project and give it a name. It runs in Helsinki, region eu-central-1 — see Regions.

3. Connect your Git provider

   Install the HostStack GitHub App — or connect GitLab, Bitbucket or Codeberg — and give it access to the repository you want to deploy. You'll be asked the first time you pick a repository for a service.

4. Create a service from the repository

   In the project, click New Service, pick the repository and branch, and choose a type — Web service for anything that answers HTTP on a public URL. The build and start commands are detected; you only need to change them if the detection is wrong.

5. Watch the first deploy

   Creating the service starts its first deploy straight away. The build log streams on the service page, and the service goes Live once its container answers the health check. From then on, every push to the branch deploys again.

Or do it from the terminal

The same five steps with the CLI, the SDK, or an AI agent through the MCP server. Create an API key first under Settings → API keys in the dashboard.

npm install -g @hoststack.dev/cli
hoststack login --key hs_live_...

hoststack projects create --name "My app"
# → prj_...

hoststack services create --name web --type web_service \
  --project prj_... --repo acme/my-app --branch main
# The first deploy starts on its own. Follow it with:
hoststack deploy list svc_...
hoststack deploy logs svc_... dpl_...

import { HostStack } from '@hoststack.dev/sdk';

const hs = new HostStack({ apiKey: process.env.HOSTSTACK_API_KEY! });
const teamId = 1; // "Team ID" in the output of: hoststack whoami

const { project } = await hs.projects.create(teamId, { name: 'My app' });

// Creating a service with a repo starts its first deploy.
const { service, deployId } = await hs.services.create(teamId, {
  projectId: project.id,
  name: 'web',
  type: 'web_service',
  githubRepo: 'acme/my-app',
  branch: 'main',
});

Create a HostStack project called "My app", then a web service
called "web" in it from the GitHub repo acme/my-app on main,
and tell me when the first deploy is live.

What a deploy does

Every deploy — the first one, a push, or a manual one — runs the same pipeline:

A web service is served at a URL like web-a1b2.hoststack.dev with HTTPS from the start. Add your own domain under Custom domains.

If the first deploy fails

Build failed

Read the build log on the deploy — the error is almost always in its last twenty lines. Check that the lockfile (package-lock.json, bun.lock, poetry.lock …) is committed, and that the build command works in a clean checkout.

Health check failed

The container started but never answered. Make sure the app binds to 0.0.0.0 — not localhost — on the port in PORT, and that the health-check path returns a 2xx or 3xx.

Build timed out

A build gets 30 minutes, and that's also the most a service can be given — the per-service setting only shortens it. Check the log for a step that hangs (an install waiting on a prompt, a test suite in the build command), and try hoststack deploy trigger svc_... --clear-cache if the build cache has gone stale.

Next steps

• Add a databaseManaged Postgres, MySQL, MongoDB or Redis, linked in with DATABASE_URL.
• Set environment variablesSecrets and config, per service or shared across services.
• Use your own domainPoint a domain at the service and get HTTPS automatically.
• Tune the buildRuntimes, build and start commands, Dockerfiles and rollback.