From project or agent bundle to production.

Install the BlackSails .NET global tool:

dotnet tool install --global BlackSails.Cli

Sign in. The CLI opens a browser-based device flow, so no password or long-lived API key is entered in your terminal.

blacksails login

From the directory containing your web project, create and link a BlackSails application:

cd src/MyWebApp
blacksails init

The command writes a blacksails.json file. Commit this file with your project—it contains application coordinates, not credentials.

Creating and linking the application does not require a payment method. When you are ready to put it online, activate a plan from the dashboard's Billing page. The CLI checks this before building the first live release.

Ship the first release:

blacksails deploy

To build without a local SDK, connect a Runnable operator token on the application page, add the standard .runnable/workflows/blacksails.yml workflow to the repository, then choose the Git ref and project path in BlackSails.

Create an agent bundle, validate it locally, and deploy it to an agent application created in the dashboard:

blacksails agent init ./support-agent
blacksails agent validate ./support-agent
blacksails agent deploy ./support-agent --app support-agent

The ZIP contains agent.yaml, a root Markdown instruction file, and optional skills/<slug>/SKILL.md resources. It cannot contain JavaScript, binaries, hooks, links, shell commands, or other executable customer code.

Choose a managed OpenAI or Anthropic catalog model, or reference a named BYOK secret. Remote MCP servers require public HTTPS endpoints and exact tool allowlists. Skill metadata can never expand the bundle's declared capability policy.

BlackSails intentionally supports a narrow deployment target so the path to production stays predictable.

• A project using Microsoft.NET.Sdk.Web
• .NET 8, .NET 9, or .NET 10
• A framework-dependent application that can run on Linux x64
• A single unambiguous web project, or an explicit --project path
• A published artifact no larger than 512 MB compressed

Dockerfiles and non-web .NET projects are rejected. If you need a custom operating system image or a non-.NET runtime, BlackSails is not the right deployment target yet.

Set production configuration without placing the value in shell history:

blacksails env set DATABASE_URL
blacksails env list
blacksails env delete DATABASE_URL

env set prompts for a hidden value. For CI or a password manager, stream the value over standard input:

blacksails env set DATABASE_URL --stdin

Names keep their exact capitalization. For nested .NET configuration, use two underscores—for example, ConnectionStrings__MongoDB maps to ConnectionStrings:MongoDB.

Every application keeps its stable Black Sails hostname. After activating a plan, a workspace owner can attach additional domains from the application's Domains panel.

1. Enter an apex domain such as example.com or a subdomain such as app.example.com.
2. Add the unique Black Sails TXT record and select Verify to prove ownership. A pending claim is never attached to the public gateway.
3. Add the recommended A record for an apex domain or CNAME record for a subdomain, then verify again after DNS propagates.
4. Black Sails enables routing only after the domain is both owned and ready for managed HTTPS.

List recent releases and inspect a deployment directly from the project directory:

blacksails deployments
blacksails logs
blacksails logs DEPLOYMENT_ID

Restore a previous healthy release by ID, or let the CLI prompt from the available history:

blacksails rollback
blacksails rollback DEPLOYMENT_ID

A new release receives production traffic only after its configured health check passes. When a release fails readiness, the previous healthy version remains current.

Every deployed web application is automatically placed behind Railway's CDN. Vercel keeps routing the Black Sails hostname and custom domains, while authenticated or cookie-bearing requests bypass the shared Railway cache.

Enable managed blob storage from the application's Storage & CDN panel. Black Sails creates a private bucket near the runtime and injects BLACK_SAILS_BLOB_API_URL and BLACK_SAILS_BLOB_TOKEN into the application. Railway credentials are never exposed to customer code.

• Create 15-minute upload grants through the REST API for objects up to 100 MB.
• Use stable CDN URLs for public objects and short-lived signed URLs for private objects.
• List metadata, delete objects, pause writes, and keep reads live while compute is suspended.

Create an application-scoped service token from Dashboard → Service Tokens, grant deployments:write, and save the one-time secret as BLACKSAILS_TOKEN in GitHub.

- uses: blacksails/deploy-action@v1
  with:
    application: my-api
    project: src/MyApi/MyApi.csproj
  env:
    BLACKSAILS_TOKEN: ${{ secrets.BLACKSAILS_TOKEN }}

The action associates the checked-out commit SHA with the release, waits for readiness, and exposes the production URL and deployment ID as outputs.

Workspace owners can rename an application, suspend or resume production compute, archive or restore it, and permanently delete it from the application page.

• Rename changes the display name but preserves the slug and hostname.
• Suspend closes production routing before scaling compute to zero.
• Archive preserves configuration and deployment history; restore leaves production suspended until explicitly resumed.
• Permanent deletion requires typing the stable slug and removes domains, artifacts, compute, secrets, deployment history, and application-scoped tokens.

blacksails init creates the deployment configuration at the repository path where you ran the command.

{
  "applicationId": "your-application-id",
  "project": "MyWebApp.csproj",
  "environment": "production",
  "healthCheckPath": "/health"
}

Use --health-check during initialization to set a local absolute path. Query strings, fragments, and external URLs are not accepted.

blacksails init --health-check /health/ready