Build an app on Newday

Before you start: prerequisites and responsible actors

Batteries are scoped platform services your App explicitly binds: for example a development database, Secrets, identity/authz, sync or configured memory/inference. Provisioning a battery and binding runtime access are separate actions; a login alone grants neither.

Agent prerequisites: an admitted account, an OAuth client and grant with the operation scopes, ordinary shell/OpenSSH/Git tools, and an external OCI builder/publisher. Choose the stack and include dependencies in its image before starting. Discover current capabilities and schemas before provisioning. Keep credentials in private client storage, never chat, source or image layers.

Operator prerequisites for SSH development: prepared workspace capacity, enabled runtime/database/artifact services, a compatible image, and a connecting device enrolled and mapped on Headscale. listEnvironmentAccessPeers shows mappings available to your identity; it does not enroll a device. The operator must supply missing infrastructure through its authorized procedures. Record operator handoffs separately from agent actions.

External API access is optional and closed by default. Existing scoped OpenRouter access uses egress_binding with profile openrouter and the owning component_id, explicit operator admission of that Component, execution-bound proxy credentials and a private CONNECT proxy. Supply the provider key through an explicitly bound Component Secret. Discover the egress schema and image transport requirements; direct internet calls remain denied. New providers and package registries need a separate operator destination/authority decision. API traffic/time limits do not imply package-download support.

1. Connect and discover

Newday hosts your apps and supplies scoped platform services. Your external coding agent owns planning, source editing, tests and image builds. You can build locally or use an SSH development Environment.

Add https://botfolio.com/v1/mcp as a remote MCP server using OAuth. Clients supporting automatic OAuth registration and PKCE can leave Client ID and Client Secret blank when registration is enabled. Sign in with an admitted Newday account and review access. Otherwise use an operator-admitted OAuth client; never borrow administrator credentials.

Read https://botfolio.com/v1 for discovery and https://botfolio.com/v1/openapi for canonical operation IDs, request schemas, scopes and MCP tool names. Call listCapabilities and list existing Spaces/Apps before creating resources. MCP tools/list is filtered by your authority and configured capabilities. An unavailable capability may need operator setup.

MCP manages lifecycle and resources; it does not provide shell, file-editing or terminal tools. Your agent needs its own shell/SSH tools and an external image builder. If using the repository CLI, newday call OPERATION_ID --args @request.json invokes the canonical operation; there is no newday init or newday dev shortcut. CLI argument files use the exact public parameter names: path IDs such as parent_id at top level, JSON request content under body, and headers as Idempotency-Key or If-Match (not idempotency_key). For example, createSpace takes {"body": {"name": "Example", "slug": "example"}, "Idempotency-Key": "YOUR-UNIQUE-KEY"}.

2. Set up development resources

A Space groups Apps. An App contains Components; each Component owns repositories, databases, Secrets and compute. Use createSpace, createApp and createComponent, or reuse the user's selected resources.

Create the release App, then a separate development App in the same Space with development_of set to the release App ID. Create a Component and repository in each. The association does not grant cross-App access. Explicitly provision development databases, Secrets and configured/App batteries in the development Component.

Inspect schemas rather than guessing arguments or translating operation IDs into MCP names. Persist each mutation's original Idempotency-Key and returned Operation ID. Poll getOperation using its state field to succeeded, failed or cancelled; an accepted request is not readiness. After an uncertain create, observe the original intent instead of issuing another create. Supply current ETags where required; reread after a stale-version response.

Use migration database credentials for a separate migration Job and runtime credentials for the app. Keep development and release database, Secret and battery bindings separate. A local OAuth login alone does not provide App runtime access.

3. Prepare an image and source

Build a compatible development image externally with your language, dependencies, Git, OpenSSH and an app startup command. Use /workspace for persistent editable source. The image must support the Environment SSH contract; consult the Environment and access schemas. The verified worked example in the Markdown guide supplies complete Python image/source files; it is a synthetic development demonstration, not a production template or universal IDE image.

For SSH compatibility, provide a dev account with UID/GID 10000 and a usable shell, and run the image as 10000:10000. Start /usr/sbin/sshd -D -e -f /var/run/core-environment-access/sshd_config alongside your development server when that mounted config is present. Use Core's supplied configuration and keys; target Ed25519 host keys use the native OpenSSH format. HTTP readiness and a ready access lease do not prove your sshd started: verify an actual strict-host-key SSH command. Run the app on the declared port, expose its readiness path, and preserve the prepared /workspace root permissions.

Use issueRepositoryCredential for scoped OCI publication, push with an ordinary OCI client to the returned repository namespace, then resolveRepositoryManifest for the admitted immutable image reference. Revoke the publication credential after use. Never bake credentials into source or image layers.

Prepare dependencies in the image: development compute has no blanket internet access or host Docker socket. Transfer source using SSH stdin or Git bundles; scoped native Git operations can run externally. New repositories have an initial commit: clone before editing or push a new branch without overwriting it.

4. Start and connect over SSH

The operator must prepare workspace capacity and enroll/map your connecting device on the private Headscale network. Discover your authorized mappings with listEnvironmentAccessPeers. Core does not silently enroll a physical device. Request core:environments:access:read and core:environments:access:write alongside the scopes needed for compute and resources.

Call createEnvironment under the development Component using an admitted image digest, artifact_binding, command, resource limits, development workspace/idle settings and private_access with transport headscale and protocol ssh. For battery-connected development use the supported network/broker/database bindings from the schema. The example body below illustrates this configuration; replace every placeholder and use your image's actual startup command. The shown /opt/app/start.sh belongs to the verified worked example.

Call startEnvironment with the current ETag, poll its Operation, and read the resulting execution. Request createEnvironmentAccess with that execution_id, authorized peer_id, ssh_public_key and ttl_seconds, plus the Environment ETag. Refresh nearly expired OAuth tokens first: SSH access is capped by the token's remaining lifetime.

Poll the access Operation and use its returned endpoint and known-hosts record with ordinary OpenSSH as dev from the mapped device. Verify host keys; every restart requires current connection information. Edit and test in /workspace. Keep execution-mounted credentials out of that persistent directory. SSH shells may need an image-owned adapter to access the application's runtime environment.

5. Preview and use batteries

Create an owner-only development Route in the same Component. After readiness, selectRoute with environment_id, execution_id and the current Route ETag. Open its returned URL using owner login, or issue a short-lived createRouteCredential (maximum 900 seconds). Never put bearer credentials in URLs.

Run your framework's development server on the declared port and readiness path. HTTP and WebSocket preview support source changes without a new image or execution when your app implements reload. Discover and explicitly configure only the batteries your app needs; runtime identity and bindings scope their use.

6. Stop, resume and preserve work

stopEnvironment closes compute, SSH and preview execution access while retaining /workspace. Wait for observed execution cleanup before restarting. Restart creates a fresh execution, runtime credentials and host key; obtain new SSH access and explicitly select the new preview execution.

Execution lifetime is at most eight hours and idle timeout at most one hour. Authenticated SSH sessions and interactive input count as activity; health polling and application output do not keep the Environment alive. Idle expiry retains source. A long control-plane outage can also fence execution; restart/select restores access after cleanup.

Commit and push source regularly. Stopped Environments retain their workspace slot. deleteEnvironment explicitly erases workspace data and frees the slot after verified cleanup; it is not a stop command. Capacity is operator-configured and bounded. Unattended workspace backup scheduling, arbitrary IDE/SFTP support and direct physical-device acceptance are outside the tested terminal-first release.

Common errors and recovery

Missing capability or an empty peer list: identify the missing scope, configured service or device mapping and ask its responsible operator; do not substitute administrator credentials. Workspace capacity unavailable: stop retains its slot; delete only disposable work you intend to erase, or have the operator prepare approved capacity.

Stale ETag: reread the resource and reconsider the intended change. An Operation still pending or an uncertain create: poll/observe the original intent and target, preserving its Idempotency-Key; do not create a duplicate. Failed startup: inspect public Operation/execution errors and verify the image command, UID, readiness, mounts and bindings before retrying a repaired execution.

SSH lease too short: refresh the OAuth token before issuing new access, then honor the returned expires_at. This does not renew existing sessions. Stale SSH host key or unavailable preview after restart: fetch the new execution, issue new access, use its known-hosts record and select that exact ready execution with a current Route ETag.

Dependency download denied: prepare dependencies externally in the image or request a concrete supported package profile; do not assume the OpenRouter profile admits registries. Wrong-Component database/Secret/battery binding: provision the intended development or release resource separately. resource_in_use during cleanup: observe execution cleanup and retire dependencies through their public operations before deleting catalog parents.

7. Release the tested source

Commit the tested workspace source and transfer that exact commit or Git bundle to an external builder. Push through a scoped native Git credential. Build a release image containing that source and publish it into the release Component's repository; resolve its immutable digest.

Use createDeployment with explicit release database, Secret and battery bindings. Wait for readiness, select the release Route and run the same functional checks. The editable workspace itself is not a release artifact.

Revoke temporary publication, SSH and preview credentials after use. Stop the development Environment when finished; delete it only when the user intends to erase the workspace. Report actual test/release results and remaining limitations. Do not claim provider, device or IDE acceptance from synthetic tests.

8. Verified worked example

The Markdown guide linked above includes the complete verified Python/PostgreSQL source, exact public calls and ordering, native publication and SSH commands, operation polling, failure recovery and cleanup. It records the actual tested commit, immutable release and explicit operator handoffs; no access to the platform repository is required.

Example createEnvironment body

Use the development Component as parent_id. Replace the placeholders with returned IDs and the admitted worked-example image.

{
  "command": [
    "/bin/sh",
    "/opt/app/start.sh"
  ],
  "port": 8080,
  "image": "botfolio.com/core/REPOSITORY_ID@sha256:DIGEST",
  "artifact_binding": {
    "repository_id": "REPOSITORY_ID"
  },
  "cpu_millis": 250,
  "database_binding": {
    "database_id": "DEVELOPMENT_DATABASE_ID"
  },
  "development": {
    "idle_timeout_seconds": 3600,
    "workspace_mib": 1024
  },
  "memory_mib": 256,
  "network": "database",
  "private_access": {
    "protocol": "ssh",
    "transport": "headscale"
  },
  "readiness_path": "/health",
  "scratch_mib": 32,
  "startup_timeout_seconds": 120,
  "timeout_seconds": 7200
}