Deploy your first app

In this guide you deploy a one-file app, open it, and share it with one other person. It takes about 5 minutes.

Before you start

Install the CLI.
Sign in. The first time, the dashboard asks you to accept the terms of service. You can’t approve the CLI’s sign-in until you have.

Create a workspace.

Every app lives in a workspace, and signing up doesn’t create one. Pick a short name, called a slug, of up to 30 lowercase letters, digits and single dashes. It goes into every app’s name and address.
Terminal window
```
forculus workspace create acme
```
```
Created workspace acme. You're its owner.
```
Slugs are unique across Forculus. If someone already has acme:
```
error: That short name is taken by another workspace, or one deleted in the last 30 days. Pick another.
```
A new workspace starts on the Free plan. See Workspaces and roles for what a workspace holds.

Write an app.

Make a directory called hello with one file, index.js:

export default {
  async fetch(request) {
    // For display only. To decide what someone may do, verify the identity token with an SDK.
    const email = request.headers.get("x-forculus-email") ?? "there";
    return new Response(`Hello, ${email}.\n`);
  },
};

A directory with an index.js and no package.json deploys as a Worker, with nothing to install or build. Check what the CLI sees:

forculus detect ./hello

a Worker
  because it has index.js

Deploy it.
Terminal window
```
forculus deploy acme/hello ./hello --create
```
```
a Worker
  because it has index.js
Version 1 is going live. Waiting for it ...
Version 1 (8b217ef9bf3c) is live.
https://hello--acme.forculuslabs-apps.tech
Scan: nothing found (no lock file).
```
acme/hello is the workspace, then the app’s own slug. --create creates the app if it doesn’t exist yet. The app is private, so only you can open it. The line under is live is its address, https://<app>--<workspace>.forculuslabs-apps.tech. The last line is what the scan of your files found. With no lock file, there are no packages to check.
Open it.

Open the address in your browser. The first time, you’re sent to sign in to the dashboard, then back to the app, which says:
```
Hello, ada@example.com.
```
forculus open acme/hello prints the address again. To call the app from the terminal as yourself:
Terminal window
```
forculus curl acme/hello
```
```
Hello, ada@example.com.
200 OK
```
Share it.
Terminal window
```
forculus share acme/hello grace@example.com
```
```
grace@example.com can now use acme/hello as a viewer. We emailed them the app's link.
```
Grace gets an email with the app’s address. If the day’s invitation limit is reached, the share still works, but no email goes out and the CLI says so. Send her the address yourself then. She signs in with a code sent to her email and sees Hello, grace@example.com. She doesn’t need to be in your workspace, and she can’t see anything else in it.

Anyone you haven’t shared the app with gets 404 not found after they sign in, even members of your workspace. In a browser they see Nothing to open here, the same page as for an app that doesn’t exist.

See who has access:
Terminal window
```
forculus access acme/hello
```
```
owner    ada@example.com
viewer   grace@example.com
```
You own the app because you created it. To take access away, run forculus unshare acme/hello grace@example.com. Access ends within 60 seconds, open connections included.

Deploy again

Run the same command after every change. --create does nothing once the app exists, so you can leave it in:

forculus deploy acme/hello ./hello --create

a Worker
  because it has index.js
Version 2 is going live. Waiting for it ...
Version 2 (c02ed76b2040) is live.
https://hello--acme.forculuslabs-apps.tech
Scan: nothing found (no lock file).
Version 1 may still answer some requests for a minute or two, until this one reaches every location.

Each deploy makes a new version, and it goes live when the upload finishes. forculus versions acme/hello lists them:

   2  deployed  2026-09-23  ada@example.com (live)
   1  deployed  2026-09-23  ada@example.com

forculus rollback acme/hello 1 puts version 1 back. See Versions and rollback.

In a script, use --json to get the result as JSON, with the address in url and the version in number:

forculus --json deploy acme/hello ./hello

If something goes wrong

Deploying to an app that doesn’t exist, without --create. A workspace owner or admin sees every app, so they’re told it isn’t there:

error: There's no app hello in acme. `forculus app list acme` lists its apps. `forculus deploy acme/hello ./hello --create` makes it.

A member may not see an app that exists, so they’re told it’s missing or not shared with them. A GitHub Actions run gets this answer too, even one an owner set up:

error: App acme/hello not found, or it isn't shared with you. `forculus app list acme` shows the apps you can see. If it doesn't exist, `forculus deploy acme/hello <dir> --create` creates it. If that says the name is already used, ask a workspace owner or admin to share it with you. `forculus workspace list` shows your workspaces.

The Free plan allows three apps:

error: This workspace has 3 apps. The Free plan allows 3. Delete one or upgrade. Team allows 25 apps. Billing: https://app.forculuslabs.tech/w/acme/billing

A server in a container (Python, Go, Rust, or a Node server) on the Free plan:

error: The Free plan only runs JS and static apps. Container apps, like Python, Go, Rust and Node servers, need a paid plan. Team runs container apps. Upgrade the workspace at https://app.forculuslabs.tech/w/acme/billing

Your role in the workspace, or on the app, doesn’t allow the change:

error: You don't have permission to do that.

The app is shared with you, but you aren’t in its workspace. Sharing lets you open an app, not deploy to it:

error: acme/hello is shared with you and you can open it. You aren't in the acme workspace, though, so you can't see or change anything else about it. `forculus app list --shared` lists what's shared with you@example.com.

Not signed in:

error: You're not signed in. Run `forculus login`.

The app deployed, but answers with a 500, or with a 502 that forculus curl says came from Forculus after the app got the request. Your app threw an exception, and its log shows it:

forculus logs acme/hello

See Logs.

Next steps

Start from a template: an app that checks who is calling, a team list with a database, or an Express or FastAPI server.
How deploy decides what to build, for anything bigger than one file.
Check who is calling with an SDK, instead of reading a header.
Share an app: roles, and opening an app to the whole workspace.
Use with your AI agent, so your agent can deploy for you.