aux4/cloud

Deploy and run aux4 packages in the cloud.

Installation

aux4 aux4 pkger install aux4/cloud

Quick Start

# Login
aux4 aux4 login

# Deploy a package (VM name defaults to "hello")
aux4 aux4 cloud deploy --package david1/hello --scope david1

# Deploy an aux4/api package as a managed HTTPS API
aux4 aux4 cloud deploy myapi --package david1/myapi --scope david1 --api

# List scopes with deployments
aux4 cloud

# List VMs in a scope
aux4 cloud --scope david1

# Run a command remotely; the VM's scope is resolved automatically
aux4 cloud hello say hello --name David

# Disambiguate only when the same VM name exists in multiple scopes
aux4 cloud hello --scope david1 say hello --name David

# View execution logs
aux4 aux4 cloud logs --scope david1

Environment Variables

| Variable | Description | |----------|-------------| | AUX4_CLOUD_SCOPE | Default scope for cloud operations | | AUX4_CLOUD_API_URL | Cloud API base URL (default: https://api.aux4.cloud) | | AUX4_CLOUD_VM | Default VM for webhook create (used when --vm is omitted) |

Commands

Running Cloud Commands

aux4 cloud                                    # List scopes with deployments
aux4 cloud --scope <scope>                    # List VMs in a scope
aux4 cloud <vm> [command] [flags]             # Resolve the VM's scope and run remotely
aux4 cloud <vm> --scope <scope> [command]     # Override scope when the VM name is ambiguous

VM names are resolved across every scope you can access, including managed VMs. If a name exists in more than one scope, the command stops and lists the matching scopes so you can select one with --scope. AUX4_CLOUD_SCOPE provides the same override for scripts and shell sessions.

Trailing --flags are forwarded to the remote command as run params — e.g. aux4 cloud kb kb search --query "pricing plans" runs kb search --query "pricing plans" on the VM. Piped stdin is forwarded too and can be combined with flags: echo "note" | aux4 cloud kb kb add --content "hello world". Flag values are passed as structured data and quoted injection-safely by the VM runtime, so spaces and shell metacharacters in a value stay literal.

Management

aux4 aux4 cloud deploy --package <scope/name> --scope <scope>           # Deploy a package
aux4 aux4 cloud deploy web --package <scope/name> --scope <scope> --size md --timeout 60
aux4 aux4 cloud deploy myapi --package <scope/name> --scope <scope> --api  # Deploy as an HTTP API
aux4 aux4 cloud deploy web --package <scope/name> --scope <scope> --env API_KEY=secret  # Seed env vars
aux4 aux4 cloud config set <package> --scope <scope> --key value  # Set config
aux4 aux4 cloud config get <package> --scope <scope>              # View config
aux4 aux4 cloud logs <vm> --scope <scope> --since 1h        # VM runtime logs
aux4 aux4 cloud delete <package> --scope <scope>                  # Remove deployment

VM Logs

View a VM's runtime logs, pulled from its Lambda's CloudWatch log group and filtered by time range. Logs are execution-based — one invocation per command run.

aux4 aux4 cloud logs <vm> --scope <scope>                 # Last hour
aux4 aux4 cloud logs <vm> --scope <scope> --since 2d      # Last 2 days
aux4 aux4 cloud logs <vm> --scope <scope> --start 2026-08-20 --end 2026-08-21
aux4 aux4 cloud logs <vm> --scope <scope> --follow        # Stream (tail -f)

| Flag | Description | Default | |------|-------------|---------| | --since | Relative window (1h, 30m, 2d); ignored if --start is given | 1h | | --start | Range start (RFC3339 or YYYY-MM-DD) | — | | --end | Range end (RFC3339 or YYYY-MM-DD) | now | | --limit | Max lines per fetch | 100 | | --follow | Stream new lines as they arrive | false |

VM Environment Variables

Set custom environment variables on a running VM. Values are encrypted at rest under a per-scope key and applied to the live VM immediately — no rebuild. Variable names must be at least two characters and start with a letter.

aux4 cloud <vm> env list                                  # List (values masked)
aux4 cloud <vm> env set API_KEY=secret DB_HOST=db          # Set one or more
aux4 cloud <vm> env unset API_KEY DB_HOST                  # Remove one or more

Add --scope <scope> only when the VM name exists in multiple accessible scopes.

You can also seed env vars at deploy time with the repeatable --env flag; they are re-applied automatically on every redeploy.

aux4 aux4 cloud deploy --package aux4/kb --scope myscope --env API_KEY=secret --env DB_HOST=db

Note: values are stored encrypted and never returned in the clear — env list shows names with masked values.

Webhooks

Register inbound webhooks that run a VM command when they receive a signed HTTP request — letting external systems (GitHub, GitLab, Stripe, Slack, Discord, or any custom sender) trigger work in the cloud.

aux4 aux4 cloud webhook presets                                    # List auth presets to pick from
aux4 aux4 cloud webhook create --vm <m> --command <cmd> --preset github --scope <scope>
aux4 aux4 cloud webhook list [--vm <m>] --scope <scope>       # List webhooks
aux4 aux4 cloud webhook show <id> --scope <scope>                  # Show one webhook
aux4 aux4 cloud webhook rotate <id> --scope <scope>               # New signing secret (shown once)
aux4 aux4 cloud webhook enable <id> --scope <scope>               # Re-enable
aux4 aux4 cloud webhook disable <id> --scope <scope>             # Turn off without deleting
aux4 aux4 cloud webhook delete <id> --scope <scope>              # Remove

Choose auth with a provider --preset (see webhook presets) or an explicit --authType (hmac, token, ed25519, url-secret). For symmetric types the signing secret is generated and printed once at creation; for ed25519 supply the sender's public key with --signingSecret. Use --event <filter> to limit which events fire the webhook.

| Flag | Description | Default | |------|-------------|---------| | --vm | VM that runs the command (or AUX4_CLOUD_VM) | required | | --command | Command to run when the webhook fires | required | | --preset | Auth preset name (mutually exclusive with --authType) | none | | --authType | hmac, token, ed25519, or url-secret | none | | --signingSecret | Signing secret (generated if omitted for symmetric types; required public key for ed25519) | none | | --event | Event filter (string or JSON) | none |

Note: the signing secret is shown only once — at create and rotate time. Save it immediately; it cannot be retrieved later, only rotated.

Deploy Options

aux4 aux4 cloud deploy [<vm>] --package <scope/name[@version]> --scope <scope> [options]

The VM name is the first positional argument (the deployment's identity, later used by run, logs, and env). When omitted it defaults to the package name for a single-package deploy.

| Flag | Description | Default | |------|-------------|---------| | <vm> | Positional VM name (deployment identity) | package name | | --package | Package to install ([repo:]scope/name[@version], repo default public); repeatable for a multi-package VM | required | | --scope | Target scope | required | | --api | Deploy as an HTTP API served behind an API Gateway (requires exactly one --package) | false | | --version | Default version for packages given without @version | latest | | --size | VM size: xs, sm, md, lg, xl | sm | | --disk | Disk (storage) size in GB; min 0.5, max depends on --size (xs 2, sm 4, md 6, lg 8, xl 10), enforced by the API | 1 | | --timeout | Lambda timeout in seconds | 120 | | --env | Environment variable NAME=value to set on the VM (repeatable) | none |

API deployments. Passing --api deploys a single aux4/api package as a managed HTTPS API: the VM runs the full Fastify app (REST routes under /api/, static assets under /static/, file downloads) behind a dedicated API Gateway. The gateway URL is printed when the deploy completes. Without --api, the VM is a command runtime you invoke with aux4 cloud <vm> ….

Package Spec and Hub Repository

Each --package is a spec of the form [<repository>:]<scope>/<name>[@<version>]. The optional <repository>: prefix selects which hub repository the package is installed from — one of public (default), private, or system. The repository is per package, so a single VM can mix a private package with public dependencies. Your access token authorizes reading a private/system repository; the prefix tells the builder which repository to install from.

# public (no prefix needed)
aux4 aux4 cloud deploy --package aux4/config --scope myscope

# a private package
aux4 aux4 cloud deploy --package private:myscope/api --scope myscope

# a mix: one private package + a public dependency, one VM
aux4 aux4 cloud deploy api --package private:myscope/api --package aux4/config --scope myscope

# pin a system package version
aux4 aux4 cloud deploy --package system:aux4/cloud-file-sync@0.0.9 --scope myscope

Each package's repository is stored on the deployment record and re-applied automatically on every redeploy.