BudgethostAPI DOCUMENTATION
API v1OpenAPI
BUDGETHOST CLIREST / JSON

Deploy from your computer

Link your project once. Deploy updates with one command. Choose the setup for your operating system.

The Budgethost CLI uploads your project, builds it on Budgethost, waits for the deployment result, and prints its public URL when available. You do not need Docker on your computer for source deployments.

CLI version: 0.1.0. Requires PowerShell 7.4 or newer, including on macOS and Linux. Windows PowerShell 5.1 is a different program and cannot run this CLI.

Before you start#

Create and configure your service in Portal: set its container port, readiness check, environment variables and persistent storage. Download a service-scoped token's .env credentials and keep it outside your project. This CLI deploys an existing service; it does not create services or configure databases, storage or secrets for you.

Your source project needs a Dockerfile and .dockerignore at its root. An AI assistant can prepare these for your app. The Dockerfile must produce a Linux container that listens on the port configured in Portal.

Windows setup#

Install PowerShell 7 from a terminal:

winget install --id Microsoft.PowerShell --source winget

Open PowerShell 7 from the Start menu. Check that $PSVersionTable.PSVersion reports 7.4 or newer, then download the installer:

Invoke-WebRequest `
  https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
  -OutFile "$HOME\Downloads\install-budgethost.ps1"

Review the downloaded script, then run it:

Unblock-File "$HOME\Downloads\install-budgethost.ps1"
& "$HOME\Downloads\install-budgethost.ps1"
budgethost version

If Windows blocks local scripts, follow your organization's execution-policy rules. On a personally managed computer, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned permits local scripts and downloaded scripts you explicitly unblock. Do not bypass an organization policy. See Microsoft's PowerShell installation guide for other installation options.

macOS setup#

Install PowerShell using Microsoft's macOS installation instructions. With Homebrew already installed, its PowerShell formula is another option:

brew install powershell
pwsh

You are now in PowerShell. Download, review and run the installer:

Invoke-WebRequest `
  https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
  -OutFile "$HOME/install-budgethost.ps1"

# Review the file before running it.
& "$HOME/install-budgethost.ps1"
budgethost version

Linux setup#

Install PowerShell 7.4 or newer using Microsoft's instructions for your distribution. Then start it:

pwsh

In PowerShell, download, review and run the installer:

Invoke-WebRequest `
  https://documentation.api.budgethost.io/downloads/install-budgethost.ps1 `
  -OutFile "$HOME/install-budgethost.ps1"

# Review the file before running it.
& "$HOME/install-budgethost.ps1"
budgethost version

The installer puts the CLI in $HOME/.budgethost and adds a budgethost function to your PowerShell profile. It is available in this session and future PowerShell sessions. It does not add a Bash or zsh command. To run it from those shells:

pwsh -NoProfile -File "$HOME/.budgethost/budgethost.ps1" help

In PowerShell, open your project folder. Windows example:

Set-Location "$HOME\Projects\my-app"
budgethost init -CredentialsFile "$HOME\Downloads\my-service.env"

On macOS or Linux, use your local paths, for example:

Set-Location "$HOME/projects/my-app"
budgethost init -CredentialsFile "$HOME/.service.env"

This creates budgethost.json with your service ID, API address and the path to your credentials. The token itself stays in the downloaded file. Keep the credentials private; on macOS/Linux, run chmod 600 on that file. The CLI parses the two credential values as text and does not execute the .env file.

The local credentials path is machine-specific. Keep budgethost.json out of Git or remove its credentials_file property before sharing it. In automation, use init -ServiceId YOUR_SERVICE_ID and provide SERVICE_TOKEN through your CI secret store. That environment variable takes precedence over the credentials file.

Deploy an update#

Review what will be uploaded before your first deployment and after adding files:

budgethost up -DryRun

Then deploy:

budgethost up

The CLI prints the deployment ID and stage changes, then the public URL after success. A nonzero exit code means the command failed or could not confirm success. The first public URL can take time to appear; HTTPS appears after the certificate is applied. Refresh the address later with:

budgethost url

Subsequent updates use the same budgethost up command. Configured persistent storage stays attached; the CLI does not recreate it.

Control what gets uploaded#

Source uploads include current files, including uncommitted and untracked files. Common local files are always excluded: Git metadata, node_modules, bin, obj, .env files, common private-key and database files, credential JSON files, and budgethost.json. The selected credentials file is also excluded.

Add project-specific exclusions to .budgethostignore, created by init:

# One pattern per line
uploads
backups
test-results
config/local.json
*.log

A pattern without / matches a name anywhere in the project. A pattern with / matches from the project root. These are PowerShell wildcard patterns (*, ?, [abc]), not Git/Docker ignore syntax; ! negation is rejected. Excluded folders are not traversed. Links are rejected unless excluded.

.dockerignore controls the remote Docker build context; it does not filter the archive uploaded to Budgethost. Keep secrets in Portal or the secret API. Filename filters cannot recognize secrets embedded in ordinary source files, so review the dry-run list and source contents. Build output can also reveal secrets if your Dockerfile prints them.

Resume or inspect a deployment#

If connectivity fails or you close the terminal:

budgethost up -Resume

This uses the same saved archive, deployment ID and retry keys. Changes to local source are not included in a resumed release. Do not delete local state while recovering. The CLI prevents a fresh release when the previous one is unresolved. Ctrl+C and the waiting timeout stop the local command, not the remote deployment.

budgethost status
budgethost logs
budgethost status -DeploymentId YOUR_DEPLOYMENT_ID
budgethost up -Resume -TimeoutMinutes 60

Logs are deployment/build logs, not a live application output stream. A failed deployment exits nonzero and does not trigger automatic rollback. Use the explicit rollback API when appropriate; it restores an image, not database contents or files.

Local retry state is stored under your operating system's local application-data directory, in Budgethost/deployments. Archives are removed after a confirmed terminal result; interrupted releases retain their archive for recovery. State contains a token fingerprint, never the token. Finish active deployments before rotating tokens: retry keys belong to the original credential.

Deploy a prebuilt image#

If you prefer building locally, install Docker and build for the service's target platform reported by the API capabilities. Save exactly one image with docker save:

# The image must already be built for the service's Linux target platform.
docker save --output "$HOME/my-app.tar" my-app:release
budgethost up -ImageArchive "$HOME/my-app.tar"

Use docker save, not docker export. No registry login or push is needed.

Direct API examples on each OS#

The deployment guide and slice guide include Bash, PowerShell and Node.js versions at every step. The CLI is optional; you can call the same public API directly using your preferred language.

Windows API prerequisites#

Use PowerShell 7.4+ for the PowerShell examples. They use Invoke-RestMethod, PowerShell's JSON commands and .NET archive support. No WSL is required. For Node.js examples, install Node.js 22 or newer. The Node.js source-archive example also requires tar on PATH, as provided by modern Windows. Docker is only needed for local image builds.

macOS API prerequisites#

Use Bash for the Bash examples. With Homebrew installed:

brew install curl jq python
export PATH="$(brew --prefix curl)/bin:$PATH"
bash

The examples work with macOS's tar and use Python for archive size and SHA-256, so you do not need GNU coreutils or GNU tar. The source-packaging command disables AppleDouble metadata. Keep the --format=ustar option.

You can also use Node.js 22+ or PowerShell 7.4+ on macOS. The Node.js examples use built-in modules without npm dependencies. Install Node.js from its official downloads.

Linux API prerequisites#

For Bash on Debian or Ubuntu:

sudo apt-get install bash curl jq tar python3
bash

Curl must support --fail-with-body (7.76+). Use your distribution's package manager on other Linux distributions. Alternatively, use Node.js 22+ or PowerShell 7.4+ with the corresponding examples.

Update or remove the CLI#

To update, download and run the installer again. It replaces the script, checks the published SHA-256, and leaves project configuration and deployment state intact. The checksum detects an incomplete or mismatched download; it is not a signing key.

To remove it, delete $HOME/.budgethost and remove the # Budgethost CLI function line from your PowerShell profile ($PROFILE.CurrentUserAllHosts). Remove local deployment state only when you no longer need to recover a release.

Download the CLI script · Download the installer