--- topic: prerequisites --- [← Guide home](https://embarko.ai/docs) # Before you start **On this page:** What Embarko is, Hosts you may need to reach, Talking to the person, Which route, Does the app fit?, What each route accepts Embarko is where a team's AI-built software lives and keeps evolving. You deploy; a member gets a live link at {name}.embarko.app. They are usually not a developer, so you do the hosting work and tell them the result in plain words. Call someone in the workspace a member. **What Embarko is** - The shared home for software a team builds with any AI: a page, a site, a tool or an app. Static websites and one-process server apps. - Languages: node, python, go, ruby, php, rust, java, static. - Address: {app-name}.embarko.app, or the person's own domain. - First deploy: Needs no account. It is temporary (24 hours) until claimed, unless it went through the connector. **Hosts you may need to reach** (all Embarko; allowlist them together) - `ship.embarko.ai`: The API: deploy, status, logs and every management call. - `embarko.ai`: The website: human docs, sign-in, the dashboard, deploy tokens, Showcase pages. - `{app-name}.embarko.app`: Where each deployed app is served. Open it to check the app works. - `raw.githubusercontent.com / github.com`: Only for the optional skill and its deploy script (github.com/embarko-ai/skill). **Talking to the person** Reply in 1-3 short plain sentences: what happened, and what the person needs to do only if something is needed. Do not show commands, API names, tokens, headers or logs, or describe the steps you took, unless the person asks for technical details. If the person is clearly a developer (uses technical terms, asks what you ran), talk to them that way for the rest of the conversation. Never show a token. Never invent a link, name or code: use only what Embarko's replies, this guide or the person give you. If the person asks what you ran or wants technical details, tell them plainly: commands, replies and logs are fine then. Never show a token. Say: Live · Open app · Deploy · Update · Needs attention · Fix with your AI · Member · Share · Deploy key Avoid: Provision · Runtime · Container · Build log · Endpoint · Token (say deploy key) · Deployment artifact · Infrastructure · Resource allocation · HTTP status codes Never ask: - Which port, framework, runtime or build command to use: work it out from the code. - Whether to add a Dockerfile: never add one. - Permission to continue a deploy they already asked for. - For a token before anything is live: deploy first, ask later. Ask only for: - Their identity: an email to keep the app. - A secret only they have, such as their own API key. - Access only they have, such as adding a DNS record for their domain. - A consequential decision: deleting, changing the address, going public, or spending money. Ask for that one thing, then carry on without further questions. Always tell them: - When a temporary app will be deleted (the exact time from app.expiresAt). - When something needs them, and what exactly. - When Embarko cannot do what they asked, and what you will do instead. **Stop when it works.** When the person's request works, stop. Do not suggest other Embarko features (connector, Showcase, domains, plans) they did not ask for. Telling them when a temporary app will be deleted, and offering once to keep it, is part of the job, not a pitch. Examples: - deploying: "Your app is deploying now. I'll tell you when it's live." - live: "Your app is live: {link}. It stays online until {time}; want me to keep it permanently?" - live_owned: "Your app is live: {link}." - still_building: "Still building. Nothing needed from you." - failed: "It didn't go live because of a problem in the code. I'm fixing it now." - needs_user: "I need one thing from you: {plain explanation}." - missing_secrets: "Your app needs a key before it can work. Add it here: {secrets page link}" - connect_once: "Connect Embarko to {your AI tool} once ({link}), then ask me again. After that I can deploy for you directly." - too_big_for_chat: "Your app is ready, but it's too big for me to send from this chat. That's a limit of this chat, not of Embarko or your app. Here it is as a file: {file}. Sign in at https://embarko.ai/app (signing up is free), choose Host new app, open Upload file, pick the file and name it {app-name}. It's yours to keep, and it'll be live in about a minute; send me the link and I'll check it works." - cant_send_from_chat: "I can't send apps to Embarko from this chat. That's a limit of this chat, not of Embarko, which is working fine. Here's your app as a file: {file}. Sign in at https://embarko.ai/app (signing up is free), choose Host new app, open Upload file, pick the file and name it {app-name}. It's yours to keep; send me the link once it's up and I'll check it works." - no_permission: "Your access ({your access to the app, or your role}) doesn't let me {what it was}. An Owner or Admin can give you more on Members: https://embarko.ai/app/people" **Which route** 1. **connector**: An Embarko connector is in your tools (deploy_app, read_app, update_app, app_danger_zone). Runs outside your sandbox, needs no token, and the app goes straight into the person's account: permanent, nothing to claim. 2. **http_api**: No connector, and you can run commands that reach ship.embarko.ai (for example Claude Code, Codex CLI, Cursor, Gemini CLI with open network). Works today with no setup. The first deploy needs no account; it is temporary until claimed. 3. **connect_first**: No connector, and you cannot reach ship.embarko.ai, and the person uses Claude or ChatGPT (in the browser or desktop app, or a sandboxed one without the connector). Gemini and other tools have no connector yet: go to route 4. Nothing you do from inside the chat can reach Embarko. Connecting takes the person a minute and fixes it for good. If they would rather let your sandbox reach Embarko instead, they can add ship.embarko.ai to the allowed domains of Claude's code execution (Settings → Capabilities; on a Team or Enterprise plan an Owner sets it for the organization). Then use route 2. This is their choice: mention it once, never push it. Say: "Connect Embarko to {your AI tool} once ({link}), then ask me again. After that I can deploy for you directly." Find their AI tool on https://embarko.ai/docs/connectors and use that link. Only Claude and ChatGPT have a connector today: for Gemini or any other tool, go straight to route 4. 4. **upload**: The person cannot add the connector, or the app could not be sent from the chat even in parts (see large_apps on the deploy topic). Give them the app as a file to download: the .html file itself if the whole app is one page, otherwise a .zip. They sign in at https://embarko.ai/app (signing up is free; an account is needed for this route), choose Host new app, open the Upload file tab, pick the file and type an app name. No terminal needed. The app goes into their account: permanent, nothing to claim, and schedules in its embarko.json apply. **Does the app fit?** A web app or website, one process, up to 256MB of memory. - WebSockets / live push (Socket.IO, ws): not supported. Instead: Plain HTTP requests, polling from the browser. - A crontab or a timer library inside the app (node-cron, APScheduler) for timed jobs: not supported. Instead: A schedule: Embarko calls a route of the app at the times you set (see schedules). - Background workers or several processes: not supported. Instead: Run the work inside the main app, for example right after the request that needs it. Separate apps cannot share files: each has its own DATA_DIR. Only split into two apps when the parts talk over HTTP, like a frontend and a backend (see two-apps). - Managed database or backups: not supported. Instead: SQLite under DATA_DIR. Tell the person it is not backed up. If the app needs one of these, tell the person before you deploy, not after it fails. **What each route accepts** - Connector: deploy_app takes the files themselves: [{ path, content, encoding? }]. Text as-is, binaries as base64. - HTTP multipart: A .tar.gz of the app folder in the "source" form field. Not .zip. - HTTP JSON: The same files list as the connector, as a JSON body. - Upload page: A folder, a .zip, or one .html file (any name: it becomes the home page). A .tar.gz also works. The browser packs it. Errors and retry rules for every call: see [errors](https://embarko.ai/docs/errors). **Next:** Pick your route, check the app fits, then follow the quickstart. **Related:** [quickstart](https://embarko.ai/docs/quickstart) · [deploy](https://embarko.ai/docs/deploy) --- [Guide home](https://embarko.ai/docs) · JSON: add .json