HubGuides
Deploy
Deploy local files or GitHub code and check the running app.
Deploy from your local folder, GitHub, or coding agent. Hub detects how to build and run the project.
What Hub looks for
Hub uses the first matching configuration:
| Project | What Hub does |
|---|---|
| Compose file | Runs your services together. |
Dockerfile | Builds and runs your image. |
package.json with start | Runs a Node app, building first when a build script exists. |
package.json with build, no start | Builds and serves dist, build, or out. |
index.html | Publishes a static site. |
Deployment types
Static sites serve published files without a running app container. Frontend builds can compile JSX, TypeScript, or styles before publication.
Runtime apps run a server, worker, or multiple services. A start script, Dockerfile, or Compose file selects this path.
Configure a different port
Hub sets PORT=3000 for detected Node apps. For Dockerfile apps, it reads hub.yaml, then EXPOSE, and otherwise uses 3000. It does not discover listening ports at runtime.
Your server must listen on 0.0.0.0 and the selected port. To override the port for a Dockerfile app, add:
app: my-app
services:
web:
port: 8000Run hub validate to check the file, then hub deploy. See the hub.yaml reference for all fields, validation rules, and current deployment support.
What gets uploaded
Local deployment includes tracked and non-ignored files. Without Git, Hub excludes .git and node_modules. Keep secrets out of source files; use environment variables.
Updating an existing app
Uploading to an existing app requires confirmation, including repeat uploads from the same folder. Changing a connected GitHub repository, branch, or path also requires confirmation. The CLI and dashboard ask before replacing the source; JSON output and hosted MCP return deploy_conflict instead of prompting.
After checking the target app and authorizing its replacement, use hub deploy --force for scripts or force: true for hosted MCP GitHub deployments. Agents need that authorization before retrying a conflicting deployment, including a fix-and-redeploy loop. Choose a different app name if you want to keep the existing app.
A Hub-managed Workspace cannot be replaced by a plain deployment, even with --force. Deploy custom code under another name.
Add a database or worker · Release lifecycle · Runtime and sleep · Persistent storage