# Jollop agent quickstart

Jollop deploys an existing project and returns its app URL. Use the user's chosen project directory. Website: https://jollop.run. Production control plane: https://app.jollop.run. Full guide: https://jollop.run/docs/agent-quickstart.

This is a deployment workflow for an agent with terminal and HTTPS access. A Jollop account or existing credential is required. Follow the user's chosen target, project, and sharing preferences. Do not deploy unrelated directories or change account settings.

## 1. Choose an available client

If `jollop` is installed, use it. If Jollop MCP tools are already configured, use those. Otherwise the HTTPS API below works without a CLI install or source-repository access. Do not assume a public binary download, package-manager package, or remote installer exists.

For the CLI, explicitly use SSC_SERVER=https://app.jollop.run unless the user chose another server. It loads SSC_TOKEN from the environment, then ~/.config/smallcloud/env. Preserve existing credentials and unrelated config values. Parse the config as KEY=VALUE data rather than executing it. Never display or commit tokens, session cookies, passwords, or login codes.

## 2. Authenticate

Reuse an existing credential if available. Confirm access with GET /apps on the control plane, using Authorization: Bearer <credential>. A 401 requires sign-in; a server error is not a reason to overwrite the credential.

Before starting any new CLI or API login, GET /auth/config on the control plane. It reports signups_open and email_delivery. If signups_open is false, a new user must arrange account access with the operator. If email_delivery is "log", codes are not being emailed, so do not start the default email-code login.

With the CLI, help an existing user run `SSC_SERVER=https://app.jollop.run jollop login --password` in an interactive terminal to enter their password without echoing it. Use `jollop login` without --password only when email delivery is configured and the user chooses that method. Successful login saves a user API key.

Without the CLI, use an HTTPS client with a cookie jar and JSON request bodies:

- If the user needs a new account, direct them to https://app.jollop.run. If signups_open is false, account access must be arranged with the operator before deployment. Do not attempt to enable signups.
- For an existing account with working email delivery, POST /auth/request-code with {"email":"<user email>"}. It returns a generic response, which does not prove that an account exists or mail arrived. Ask the user for the received code, then POST /auth/login-code with {"email":"<user email>","code":"<received code>"}.
- If email_delivery is "log", codes are not being emailed. Use an existing account's password through a user-controlled terminal with hidden input, or ask the user to obtain access from the operator. Never request server logs or an operator credential as a workaround.
- Password sign-in is POST /auth/login with {"email":"<user email>","password":"<password from hidden input>"}. Keep the password out of shell arguments, files, output, and chat.
- Successful sign-in sets the host-only ssc_session cookie. Using that cookie jar, POST /auth/api-keys with {"label":"coding agent"}. Read the key field from the JSON response without printing it.
- Save SSC_SERVER and SSC_TOKEN outside the project in ~/.config/smallcloud/env with mode 0600, preserving unrelated settings. Subsequent control-plane requests use Authorization: Bearer <key>.

All paths in this guide are relative to https://app.jollop.run unless explicitly stated otherwise. Send account credentials only to the chosen control-plane origin, never to deployed app hosts or unrelated domains. Use an HTTP client or protected curl configuration rather than putting credentials in process arguments.

## 3. Deploy the project

With the CLI:

    SSC_SERVER=https://app.jollop.run jollop deploy <project-directory>

The CLI also accepts an archive, public Git URL, or --image <container-ref>. With an existing MCP connection, call its deploy tool for the chosen directory.

Without the CLI:

1. Create a gzip-compressed tar archive with the project's contents at its root. Keep the archive outside the project. Exclude .git, node_modules, .venv, venv, __pycache__, .ssc, OS junk, credentials, and private environment files. Include source, dependency manifests, lockfiles, and required project assets. Do not include unrelated files from the user's home directory.
2. Choose a stable app name, normally the project directory's base name. URL-encode it. Reusing a name updates that app, so confirm the intended project before overwriting an existing deployment.
3. POST the archive bytes to /deploy?name=<url-encoded-name> with Content-Type: application/gzip and the Bearer credential. Do not wrap the archive in JSON or base64. Keep the response streaming.
4. Parse each NDJSON line. event=stage describes progress; event=done supplies id, kind, and (for web apps) url; event=error means failure. Read to end of stream: an error after a done event still means deployment failed. An HTTP 200 alone is not proof of a successful deployment.

Jollop detects supported runtimes and provisions backing services from dependency signals and observed behavior. For a Postgres app, include its database driver in the dependency manifest and use the supplied environment settings. React, Django, and PostgreSQL are examples, not a guarantee that every project structure will deploy unchanged. If deployment fails, inspect the actual diagnostics, make a targeted fix, and avoid repeated identical retries.

## 4. Verify and return the result

Use the returned app URL, not a guessed vanity hostname. Check that the expected page or API responds, and exercise one appropriate non-destructive action when access permits. Inspect GET /logs/<id> and GET /topology/<id> on the authenticated control plane when diagnosing a problem.

New deployments use secure-link visibility by default. The plain app URL may require access, so do not label an authorization page as the app or make the app public just to verify it. A control-plane browser session does not grant access to a default link-visible app; that app requires its secure link. Org-visible apps can use the signed-in browser authorization flow.

When the user asks for a secure link (as the starter prompt does), run `jollop share <id>` or POST /share/<id> with {"action":"generate"}. The API JSON response contains the url field; the CLI prints the secure link. Use that capability URL to verify and return the app, without sending the control-plane credential to the app host. This preserves secure-link visibility rather than making the app public. Do not print the capability URL in diagnostic logs or send it to unrelated services; return it privately to the requesting user. Public visibility requires the user's request.

Return the deployment's URL, what was verified, and any remaining access or application error. If app access prevents a functional check, say so. Never report a running app based only on a queued request or a partial stream.

## Reference

- https://jollop.run/docs/agent-quickstart
- https://jollop.run/docs/cli
- https://jollop.run/docs/mcp
- https://jollop.run/docs/services
- https://jollop.run/docs/sharing