Run Nook. Extend Nook.

What do you want to do?

Path	Start here	You will finish with
Run Nook on your own server	Plan a self-hosted deployment	A licensed, activated, backed-up Nook instance with a tested update and recovery plan.
Build an integration	Create your first Nook bot	A published workspace app that receives signed callbacks and calls the installation-scoped bot API.

Nook Cloud users do not need the self-hosting guides. Nook operates the infrastructure, updates, backups, and recovery for the cloud product. The bot guides apply to both Nook Cloud and self-hosted instances when the Apps platform is enabled.

Self-hosting lifecycle

1. Plan: assign an Ubuntu host, DNS names, TLS termination, mail delivery, storage, backup retention, and an operator.
2. Register: create the commercial organization in the Customer Portal and obtain a paid self-hosted entitlement. Payment processing may be bypassed during the current preview, but the entitlement boundary still exists.
3. Install: copy the signed repository and release commands from the Portal. Verify independent keys and never put a Portal credential or one-time code in a shell argument.
4. Activate: bind one deployment key to the entitlement, approve the short-lived pairing code, and create the first local owner.
5. Operate: monitor health, retain continuity backups off-host, follow signed update channels, and test recovery before an incident.
6. Decommission: revoke entitlement authority, stop the instance, preserve data for the agreed retention period, and sanitize media through an approved process.

Read the deployment planning guide →

Apps and bots lifecycle

1. Create an app in Settings → Developer Portal and save the show-once credentials securely.
2. Define an immutable manifest: commands, events, required scopes, and optional scopes.
3. Expose HTTPS interaction and event endpoints and pass the signed challenge handshake.
4. Publish a version and let a workspace administrator review scopes and channel policy.
5. Exchange the installation callback’s one-time code for an installation-scoped bot token.
6. Verify every callback before parsing, deduplicate deliveries, answer interactions within three seconds, and rotate secrets without downtime.

Build the reference TypeScript bot →

Trust boundaries worth remembering

• A Customer Portal account manages commercial ownership and entitlement. It is not a local Nook user account.
• A connected self-hosted instance sends only documented entitlement, update, notification-gateway, support, and opt-in operational metadata to central services. Local messages and files stay local.
• A bot token belongs to one installation in one workspace. Workspace identity is derived from the token; bot API paths never accept an arbitrary workspace ID.
• Nook never runs third-party bot code. Your HTTPS service receives signed JSON and calls a bounded HTTP API.
• Recovery operation keys and pairing codes are short-lived authority. Treat them as secrets, pass them through protected files or dedicated UI fields, and destroy them after completion.

Documentation conventions

• Replace values in angle brackets, such as <deployment-id>, before running a command.
• Commands marked as Portal-generated must be copied from the matching organization and entitlement. A public example is not an entitlement.
• A command block containing sudo changes the server. Read it first and confirm paths.
• nookctl deliberately fails closed. A stopped service after a rejected restore is a safety state, not a reason to bypass the receipt or edit the database manually.
• All examples use placeholder domains and tokens. Never paste a production secret into a ticket, chat message, shell history, URL, or support bundle.