--- title: "Quickstart" description: "Install cf-orbs with one command, run a first orb, and check that it works." --- > Documentation Index > Fetch the complete documentation index at: https://cf-orbs-site.mdick85.workers.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart You end with cf-orbs running in your Cloudflare account and a first Amp thread on one of your orbs. Plan on 5 to 15 minutes. One measured install took 4 min 41 s, and most of that was the push of the 1.8 GB orb image. No Docker on your machine? Use [Install with Workers Builds](/docs/guides/install-workers-builds/) instead. ## Before you start | You need | How to check | | --- | --- | | Node 22 or later | `node --version` | | Docker, running | `docker info` | | A Cloudflare account on Workers Paid | Dashboard → Workers & Pages → Plans | | wrangler logged in to that account | `npx wrangler login`, then `npx wrangler whoami` | | The Amp CLI, installed | `amp --version` | | An Amp provider token (`aop_live_...`) and its provider name | Amp → Settings → Orbs → Add Provider | The provider is the process that takes orb jobs from Amp. The **provider name** is the name you type in Amp when you add it. Write it down. Pass the same name to `init` with `--provider-name`, because a name that differs from the one in Amp doesn't work. The default is `cloudflare`: if you type `cloudflare` in Amp, you don't need the flag. A name saved by an earlier `init` wins over the default, and `init` warns you when it uses the default. You need the Amp CLI only for the first-orb command below. `init` itself doesn't run it. ## Install 1. **Make a project directory** ```sh mkdir my-orbs && cd my-orbs ``` 2. **Run init** ```sh npx cf-orbs init --provider-name ``` `init` asks for the Amp provider token. It doesn't show what you type, and the token doesn't end up in your shell history. No provider in Amp yet? Add it first in Amp → Settings → Orbs → Add Provider. The prompt names this page too. If npx asks `Ok to proceed?`, answer yes, or use `npx --yes cf-orbs`. In a terminal, `init` can ask two more questions: - **Cloudflare account.** It asks only if `wrangler whoami` lists more than one account. Type the number of the account, or pass `--account-id ` to skip the question. You'll find the account ID in `npx wrangler whoami`, and in the Cloudflare dashboard URL after `dash.cloudflare.com/`. - **workers.dev subdomain.** It asks only if the account has none. Type a short lowercase name, or press Enter to take the suggestion. The Worker URL becomes `https://..workers.dev`. You can also pass `--subdomain `. Without a terminal, `init` doesn't ask. It stops with a `Failed:` line that names the flag to add. 3. **Wait for init to finish** `init` builds and pushes the images, deploys the Worker and starts the provider. The Worker is the cf-orbs control plane, the service that starts, pauses and deletes orbs (see [How it works](/docs/concepts/how-it-works/)). You may see lines such as `deploy: registry push timed out; retry 1 of 3`. They're normal, and `init` retries by itself. When it succeeds, the last line is a command to try. What `init` does, in order: 1. Checks Node, Docker, the wrangler login and the account. 2. Checks that Containers are available on the account. 3. Writes `cf-orbs.config.jsonc`, `image/Dockerfile` and `.cf-orbs/`. 4. Registers a workers.dev subdomain if the account has none. 5. Runs `wrangler deploy`, which builds and pushes the orb image and the provider image, then deploys the Worker. 6. Checks `/v1/health` and `/v1/status`. 7. Runs the orb self-test. The Worker starts throwaway instances from the new image (this is called prewarm), and `init` waits up to 3 min for one to start. Prewarm also raises the chance that a later spawn (an orb start) finds the image already on its host. 8. Starts the provider and waits until it has run for 15 s with a clean log. `init` is safe to run again. It keeps the control token (the secret the CLI uses to call your Worker), and it keeps the Amp token unless you give a new one. ## Run a first orb This command uses your Amp credits. You can run it from any directory: ```sh amp -ox "hello from cf-orbs" --orb-provider ``` In the Amp app, pick the provider from the provider list when you start a thread. It's the one you added in Amp → Settings → Orbs. ### How to know it worked - `amp -ox` runs the prompt in a new thread and prints the agent's answer in your terminal. A slow first run is normal. - The thread shows up in the Amp app, and its setup log shows the orb starting on your provider. - `npx cf-orbs status`, run from the project directory, lists the orb under `awake orbs`. Orb ids are `amp-`. - `npx cf-orbs logs ` shows the orb's bootstrap log. The bootstrap is the Amp start-up step that connects the orb to Amp. If the command hangs or fails, see [Troubleshooting](/docs/troubleshooting/). The first spawn on a new Cloudflare host starts from the image, which takes about 45 s. Then Amp sets up the repo. ## Verify Run both commands from the project directory: ```sh npx cf-orbs doctor npx cf-orbs status ``` - `doctor` shows `PASS` on every line and ends with `All checks passed.` `INFO`, `SKIP` and `WARN` lines don't fail the run. - `status` shows `provider: running`. If a line fails, it holds its own fix. See also [Troubleshooting](/docs/troubleshooting/). ## Choose a smaller orb The default orb is 4 vCPU, 12 GiB memory and 20 GB disk. For a cheaper orb, run `init` again with `--vcpu 2`, which gives 2 vCPU, 6 GiB and 20 GB: ```sh npx cf-orbs init --vcpu 2 ``` `init` writes the new `instance` to the config and deploys again. See [Change the orb size](/docs/guides/change-orb-size/). ## Next steps - [Configure cf-orbs](/docs/guides/configure/) - [Check health and read logs](/docs/guides/check-health/) - [Add toolchains to the orb image](/docs/guides/add-toolchains/) - [Back up and restore](/docs/guides/back-up-and-restore/) Source: https://cf-orbs-site.mdick85.workers.dev/docs/quickstart/index.mdx