Added Getting Started Page for the Remote API

docs/source/configuration/remote_config.rst

@@ -20,13 +20,13 @@ the configuration is used as the default.
 .. code-block:: yaml
 
   remote_config:
-    remote_server:
-      url: "https://10.0.0.5:5000"
+    attackmate-server:
+      url: "https://10.0.0.5:8445"
       username: admin
       password: securepassword
       cafile: "/path/to/cert.pem"
-    another_server:
-      url: "https://10.0.0.6:5000"
+    another-server:
+      url: "https://10.0.0.6:8445"
       username: user
       password: anotherpassword
       cafile: "/path/to/another_cert.pem"
@@ -38,15 +38,15 @@ default connection is used when none is specified:
 .. code-block:: yaml
 
   commands:
-    # Executed on 'another_server'
+    # Executed on 'another-server'
     - type: remote
-      connection: another_server
+      connection: another-server
       cmd: execute_command
       remote_command:
         type: shell
         cmd: "whoami"
 
-    # Executed on 'remote_server' (defaults to first remote_config entry))
+    # Executed on 'attackmate-server' (defaults to first remote_config entry))
     - type: remote
       cmd: execute_playbook
       playbook_path: path/to/playbook.yml

docs/source/index.rst

@@ -22,6 +22,7 @@ Welcome to AttackMate's documentation!
    preparation/index
    configuration/index
    basic
+   remote_api_intro
 
 .. toctree::
    :maxdepth: 4

docs/source/remote_api_intro.rst

@@ -0,0 +1,156 @@
+.. _remote_api_intro:
+
+==========
+Remote API
+==========
+
+AttackMate can execute commands and playbooks on a remote AttackMate
+instance. This is useful when the tools required by a playbook, such as
+Metasploit, Sliver, browsers, or network access to a target environment, are
+available on another host.
+
+The remote setup uses two components:
+
+* `attackmate-api-server <https://github.com/ait-testbed/attackmate-api-server>`__:
+  runs on the remote AttackMate host and exposes an HTTPS API.
+* `attackmate-client <https://github.com/ait-testbed/attackmate-client>`__:
+  runs on the local/client host and sends commands or playbooks to the API
+  server.
+
+`attackmate-client` offers a CLI and a python library to execute commands and playbooks on a
+remote AttackMate server. It is only required on the client when you want to use the Remote API
+on an attackmate-api-server.
+
+The `attackmate-ansible <https://github.com/ait-testbed/attackmate-ansible>`__
+role can install and configure both sides.
+
+Requirements
+============
+
+A working remote setup needs at least:
+
+* AttackMate installed on the server.
+* attackmate-api-server installed and running on the server.
+* attackmate-client installed on the client, to access the remote API.
+* The server TLS certificate copied to the client.
+* A valid ``remote_config`` entry on the client, or provided as cli argument to ``attackmate-client``.
+* Any tools used by the remote playbook installed on the server, for example
+  ``msfrpcd`` for Metasploit commands.
+
+If you installed ``Attackmate`` on the client, it is not recommended to install ``attackmate-client``, as it will
+already have pulled that in as a dependency. 
+
+You can install just the ``attackmate-client``, if all you want to do on the client is to send remote commands
+and playbooks to the attackmate-api-server via CLI or the python library.
+
+Architecture
+============
+
+When a remote playbook uses ``cmd: execute_playbook``, the referenced
+``playbook_path`` is read on the client machine. The client then sends the
+playbook YAML content to the API server.
+
+The commands inside that submitted playbook run on the server. Therefore paths
+inside the submitted playbook, such as payload paths, temporary files, local
+uploads, or tool configuration, are resolved on the server.
+
+Sample Config
+=============
+
+Save this as ``/etc/attackmate.yml`` on the client:
+
+.. code-block:: yaml
+
+    msf_config:
+      server: localhost
+      password: hackerman
+
+    cmd_config:
+      command_delay: 2
+
+    remote_config:
+      attackmate-server:
+        url: "https://10.0.0.5:8445"
+        username: admin
+        password: securepassword
+        cafile: "/etc/ssl/certs/attackmate.pem"
+
+The ``cafile`` must point to the certificate used by the API server. If the
+certificate is missing or does not match the server, HTTPS verification will
+fail.
+
+First Run
+=========
+
+Create a small local wrapper playbook on the client:
+
+.. code-block:: yaml
+
+    commands:
+      - type: remote
+        cmd: execute_playbook
+        connection: attackmate-server
+        playbook_path: examples/remote_put.yml
+
+Run it with:
+
+.. code-block:: console
+
+    uv run attackm8 --debug remote_wrapper.yml
+
+The local attackmate should log in to the remote API server, send the referenced playbook, and
+print the remote execution result.
+
+Testing The API Server
+======================
+
+Check that the API service is reachable:
+
+.. code-block:: console
+
+    curl -k https://10.0.0.5:8445/
+
+Metasploit
+==========
+
+If a playbook uses Metasploit commands, ``msfrpcd`` must be running on the
+server and the AttackMate server configuration must match it.
+
+Example:
+
+.. code-block:: yaml
+
+    msf_config:
+      server: localhost
+      port: 55553
+      password: hackerman
+      ssl: true
+
+A common symptom of a wrong Metasploit configuration, or msfrpcd not running, is:
+
+.. code-block:: text
+
+    2026-05-20 11:01:37 INFO     | Login successful for 'admin' at https://192.168.0.30:8445. Token stored.
+    2026-05-20 11:02:37 ERROR    | Request Error (POST https://192.168.0.30:8445/playbooks/execute/yaml): The read operation timed out
+
+
+Troubleshooting
+===============
+
+``The read operation timed out``
+
+The client waited longer than its configured HTTP timeout. This can happen when
+the remote playbook is still running, waiting for a session, or stuck in a tool
+such as Metasploit. Check the server logs and any AttackMate playbook logs.
+
+You can also increase the timeout period of attackmate-client by changing DEFAULT_TIMEOUT in ``/usr/local/share/attackmate/.venv/lib/python3.12/site-packages/attackmate_client/attackmate_client.py``
+
+Server Logs
+===========
+
+If file logging is enabled for API playbook runs, inspect the configured log
+directory, for example:
+
+.. code-block:: console
+
+    tail -f /var/log/attackmate-api/*_output.log