# cTrader cBots on Linux — no Windows required

Build cTrader **cBots** in C#, compile them to `.algo` files, and run/backtest them
**entirely on Linux** — no Windows, no Wine, no cTrader desktop GUI.

This repo is a working scaffold that proves the full toolchain end to end and gives
you a starting point. The build was verified on this machine: `dotnet build` against
the official `cTrader.Automate` NuGet package produces a valid `.algo` on Linux.

## TL;DR — is it really possible?

**Yes**, with two pieces, both officially supported by Spotware:

1. **Compile on Linux** (since cTrader Desktop 4.2, March 2022). A cBot is an
   ordinary .NET class library that references the official `cTrader.Automate`
   NuGet package. `dotnet build` runs the package's MSBuild targets, which emit the
   `.algo`. No Windows, no desktop app. Spotware's own words: *"write code and
   compile it on Linux or Mac."*
2. **Run/backtest on Linux** (since cTrader 5.4, ~Aug 2025) via the official
   **cTrader CLI / Console** Docker image `ghcr.io/spotware/ctrader-console`. It
   runs `.algo` cBots headless — live and backtest — without the desktop GUI.

The nuance worth knowing: step 2 is *recent*. Before cTrader 5.4 there was no Linux
runtime, and Spotware staff said so on the forum as late as Nov 2024. Anyone working
from older information will (incorrectly) tell you it's impossible.

See [`docs/research-findings.md`](docs/research-findings.md) for the sourced details.

## Prerequisites

- The **.NET SDK** (6.0+). Nothing else is needed to compile.
  Install it locally without root: `./scripts/install-dotnet.sh`
  (drops it into `~/.dotnet`).
- **Docker** — only if you want to run/backtest via the official console image.

## Quickstart

```bash
# 1. Install the .NET SDK locally (skip if you already have `dotnet`)
./scripts/install-dotnet.sh

# 2. Compile every cBot in src/ into dist/*.algo
./scripts/build.sh

# 3. Run / backtest headless in the official cTrader console container
#    (discover the exact flags for your image version first)
./scripts/run-console.sh --help
```

After step 2 you get `dist/SampleCBot.algo` — a ready `.algo` you can also import
into the cTrader desktop/web app directly.

## Repo layout

```
src/SampleCBot/         A complete example cBot (SMA crossover)
  SampleCBot.csproj     SDK-style class library referencing cTrader.Automate
  SmaCrossOverBot.cs    The Robot class
scripts/
  install-dotnet.sh     Local, root-free .NET SDK install (~/.dotnet)
  build.sh              dotnet build -> collects dist/<ProjectName>.algo
  run-console.sh        Thin wrapper over ghcr.io/spotware/ctrader-console
dist/                   Built .algo artifacts (gitignored)
docs/research-findings.md   What the research established, with sources
```

## How it works

**Build.** A cBot project is a normal `Microsoft.NET.Sdk` class library targeting
`net6.0` with a single `<PackageReference Include="cTrader.Automate" />`. The package
ships MSBuild `.targets` that, after a successful compile, bundle the assembly into the
proprietary, encrypted `.algo` container (file magic: the ASCII bytes `algo`). The
`.algo` lands in `bin/<config>/<tfm>/`; `build.sh` collects it into `dist/`.

**Run.** `run-console.sh` mounts `dist/` into Spotware's official console container at
`/mnt/Robots` and forwards your arguments to the cTrader CLI, which hosts the `.algo`
live or in backtest without the desktop app.

## To add your own cBot

1. `dotnet new classlib --name MyBot --output src/MyBot`
2. `cd src/MyBot && dotnet add package cTrader.Automate`
3. Write a `class MyBot : Robot` (`using cAlgo.API;`) — see `SmaCrossOverBot.cs`.
4. `./scripts/build.sh` → `dist/MyBot.algo`.

## Known quirk (handled)

`cTrader.Automate` 1.0.17 names the raw `.algo` after the project's **parent folder**,
not the project — so multiple bots would collide on one name. `build.sh` works around
this by renaming each collected artifact to `<ProjectName>.algo`. (The bot's name shown
inside cTrader comes from the class metadata, not the file name, so this is cosmetic.)

## Limitations

- The cTrader **desktop app** itself is Windows/macOS only — but you don't need it for
  this workflow.
- Must be a **modern .NET 6 algo** (cTrader 4.8+). Legacy .NET Framework cAlgo bots
  must be recompiled.
- **Live trading** requires a real broker account + cTrader ID credentials passed to
  the console.
- The `.algo` format is proprietary/encrypted by Spotware; this scaffold goes *through*
  the official package — there is no independent open-source `.algo` packer.