---
topic: quickstart
---

[← Guide home](https://embarko.ai/docs)

# Quickstart

**On this page:** Which route are you on?, Deploy, Keep it (claim), What the person asks next, Store files, Connect other apps, Showcase, Stuck, or something missing?

Do the steps in order. Open a linked topic only when a step goes wrong.

> Plain words for non-developers; no commands or tokens unless they ask. Ask only for what only they can give (email, a secret, DNS access, a yes on something that cannot be undone). Never invent a link, name or code. Stop when their request works.

Picking up an app someone else started? Read its state first: [resume](https://embarko.ai/docs/resume).

## 0. Which route are you on?

| If | Then |
| --- | --- |
| Embarko tools (deploy_app, read_app...) are in your tool list | Use them. No token, nothing to claim: skip step 2. Under 150 KB in total: call deploy_app once with all the files. Do not use start_upload for small apps. Over 150 KB in total, or a long conversation: send it in parts with start_upload, add_upload_files and deploy_upload. Finish and call deploy_upload within 60 minutes, from the same token, or the upload expires (large_apps on the deploy topic). |
| You can run commands that reach ship.embarko.ai | Use the commands in steps 1-2. |
| You cannot reach ship.embarko.ai (chat app with no terminal, or a blocked sandbox) | Do not paste commands. Claude or ChatGPT: ask them to add the Embarko connector/plugin (https://embarko.ai/docs/connectors), then ask you again. Any other tool (Gemini...) has no connector yet: give them the app as a file, the .html itself if the app is one page, otherwise a .zip (a single folder inside it is fine). They sign in at https://embarko.ai/app (signing up is free), choose Host new app, open the Upload file tab, pick the file and type an app name (lowercase letters, numbers, dashes). Tell them in plain words it is this chat's limit, not Embarko's (say_to_user.cant_send_from_chat on the deploy topic). The app appears in their app list once it is built; ask them to paste its link back, then open it yourself. That app is theirs and permanent: nothing to claim, and schedules in its embarko.json apply. Keys the app needs go in its App setup tab; a custom domain in its Domain tab (see custom-domain). |

## 1. Deploy

Connector: call deploy_app with { appName, files } (binaries with encoding "base64"), then read_app { action: "status", appName } until it is final. It is already permanent: skip step 2. Under 150 KB in total: call deploy_app once with all the files. Do not use start_upload for small apps. Over 150 KB in total, or a long conversation: send it in parts with start_upload, add_upload_files and deploy_upload. Finish and call deploy_upload within 60 minutes, from the same token, or the upload expires (see large_apps on the deploy topic).

Otherwise:

```bash
tar -czf /tmp/app.tar.gz --exclude=node_modules --exclude=.git --exclude='.env*' --exclude=dist --exclude=.next --exclude=venv --exclude=.venv --exclude=__pycache__ --exclude='*.db' -C /path/to/app .
curl -sS -X POST 'https://ship.embarko.ai/apps' -H 'X-App-Name: my-app' -H 'X-Agent-Name: {your-name}' -F 'source=@/tmp/app.tar.gz'
```

Poll:

```bash
curl -sS 'https://ship.embarko.ai/apps/my-app/status'   # once the app is kept, add --oauth2-bearer $DEPLOY_TOKEN
```

Poll every 10s (2s for a static site) until final: live, failed, crashed or not_deployed. Open https://my-app.embarko.app yourself, then give the person the link and app.expiresAt in their local time.

**Done when:** You opened the link and its main feature works (a 200 alone is not enough).

**If it fails:** Follow the reply's next and code. Usual causes: not reading PORT or binding 0.0.0.0; a Dockerfile; manifest not at the top of the folder; WebSockets; a crontab or timer library (use schedules); data saved next to the code instead of DATA_DIR. Fix and deploy again, same name. 409 name taken: use a close variant (their name, or -site / -app) and mention it with the link.

**Blocked:** No reply, or 403 host_not_allowed from your sandbox: nothing was deployed, do not retry. Use the last row of step 0; if the connector is already there, deploy with it (in parts if the app is big, see large_apps on the deploy topic).

More: [deploy](https://embarko.ai/docs/deploy) (requirements and common errors) · [errors](https://embarko.ai/docs/errors) (every error code and retry rule) · [logs](https://embarko.ai/docs/logs) (why a build failed)

## 2. Keep it (claim)

**Skip if** you deployed through the connector. Otherwise the app is deleted at app.expiresAt (24 hours after the first deploy).

1. Token already in DEPLOY_TOKEN or ~/.embarko/credentials? Go to the redeploy.
2. Otherwise ask for their email and send it once (command below). They paste the token from their inbox; save it to ~/.embarko/credentials.
3. Redeploy: the step 1 command, same name, plus --oauth2-bearer {token}. The reply says claimed: true.
4. From now on send the token on every call, status included: a claimed app answers 404 without it.

body.json:

```json
{"email":"{their email}"}
```

```bash
curl -sS -X POST 'https://ship.embarko.ai/api/public/deploy-tokens/request' -H 'Content-Type: application/json' --data @body.json
```

**Done when:** claimed: true. Tell the person it is permanent.

More: [claim](https://embarko.ai/docs/claim) (rate limits and errors)

## 3. What the person asks next

Only when they ask. Check "done when" before saying it works. Over HTTP every call needs the token.

| They say | Read | Done when |
| --- | --- | --- |
| "Is it working?" | [status](https://embarko.ai/docs/status) | Status is live and the main feature works when you try it. |
| "Fix the broken form / page" | [logs](https://embarko.ai/docs/logs) | You redeployed the fix and a test submission arrives (or the page works). |
| "Keep these records" | [data](https://embarko.ai/docs/data) | A record you saved is still there after a redeploy. Tell them there are no backups. |
| "Add my API key" | [env-vars](https://embarko.ai/docs/env-vars) | The feature that uses the key works. |
| "Let people upload photos" / "Store this file" / "Generate a PDF they can download" | [files](https://embarko.ai/docs/files) | See step 4. |
| "Use my domain" | [custom-domain](https://embarko.ai/docs/custom-domain) | https://their-domain opens the app. |
| "Make it private" / "Only my team should open it" | [lock](https://embarko.ai/docs/lock) | The app asks for an Embarko sign-in (or the password) and the right people get in. |
| "Do this every morning" | [schedules](https://embarko.ai/docs/schedules) | A run you started now finished ok, and they know when it runs next. |
| "Connect it to Slack / Sheets / my CRM" | [integrations](https://embarko.ai/docs/integrations) | See step 5. |
| "Undo that update" | [rollback](https://embarko.ai/docs/rollback) | The previous version is serving. |
| "How is it doing?" | [analytics](https://embarko.ai/docs/analytics) | You told them visits and errors in one sentence. |
| "Change the address" | [rename](https://embarko.ai/docs/rename) | They said yes first, and the new address opens the app. |
| "Move it to our team workspace" / a token from another workspace | [move](https://embarko.ai/docs/move) | The move call said moved: true. A new token alone moves nothing. |
| "Delete it" | [delete](https://embarko.ai/docs/delete) | They said yes to the app by name, and it is gone. |

## 4. Store files

When the app takes uploads (photos, documents), makes files (PDFs, exports) or needs an image you have now. Every app has a file store: PUT the bytes, get a public link back. You upload with the deploy token; the running app uploads with the STORAGE_URL and STORAGE_TOKEN env vars Embarko sets for it. Not for records: those go in SQLite under DATA_DIR (see data).

```bash
curl -sS -X PUT 'https://ship.embarko.ai/storage/apps/my-app/files/hero.png' --oauth2-bearer $DEPLOY_TOKEN --data-binary @hero.png
```

**Done when:** The url in the reply opens the file, and the app saved that url with its record if it uploaded.

More: [files](https://embarko.ai/docs/files) (upload from the app, list, usage, delete, limits and errors)

## 5. Connect other apps

Offer it when the app would benefit from Slack, Google Sheets, a CRM or similar, or when they ask. One call turns Integrations on and the app gets an embedded panel where its users connect tools and build their own flows; you build the panel in by following the steps in integrations. The app must be claimed; static sites cannot use it.

**Done when:** Integrations is on, the app reads the three INTEGRATIONS_* settings, and the panel loads for a signed-in user.

More: [integrations](https://embarko.ai/docs/integrations) (the call, the mapping to viasocket's skill, and errors)

## 6. Showcase

Only if they want it public. Draft the listing, show it, publish on their yes. No image from them? Offer to screenshot the live app, upload it to file storage (step 4) and use that url: listings with a picture get opened far more. Over HTTP the app must be claimed; with the connector, use the dashboard (see showcase).

**Done when:** The listing page opens, or the event listing is waiting for the organiser and they know.

More: [showcase](https://embarko.ai/docs/showcase) (fields and approval)

## 7. Stuck, or something missing?

Check that step's topic first. If Embarko is wrong, a feature is missing or these docs are unclear, report it with one call (bug, feature request or docs problem): see feedback.

More: [feedback](https://embarko.ai/docs/feedback) (the call, and the report types)

---

[Guide home](https://embarko.ai/docs) · [Rules](https://embarko.ai/docs/prerequisites)