Skip to content

Advanced usage

Jump to bottom
Davide N edited this page Mar 26, 2025 · 7 revisions

The configuration file location

The default config.ini file contains common configurations. The location of the config.inidepends on the OS:

  • On Unix systems, it's located inside $XDG_CONFIG_HOME/ArduinoCreateAgent/config.ini as specified here. If $XDG_CONFIG_HOMEis empty, the location will be in $HOME/.config/ArduinoCreateAgent/config.ini.
  • On macOS, it's located in $HOME/Library/Application Support/ArduinoCreateAgent/config.ini.
  • On Windows, it's located in %AppData%\ArduinoCreateAgent\config.ini.

If you need to know the exact location of the config, or you need to modify it, you can use the "Open Configuration" menu in the tray icon menu.

Using multiple configurations

The agent supports multiple configuration files. The additional configurations will override the main one (config.ini). When multiple configurations are found by the agent, the tray icon menu is expanded to contain the different configurations:

To create multiple configuration files:

  1. Click the Arduino Cloud Agent tray bar icon.

  2. Select Quit Agent from the menu.

  3. Find the config.ini file (see section above).

  4. Copy config.ini or create a new ini file (e.g. example.ini) with content:

    name = your configuration name

    Add in this file other configuration options (you can override inherited values from config.ini)

  5. Restart the agent.

  6. Click the tray bar icon.

  7. Select the new configuration.

Tip: you can also use the multiple configurations feature to create a new configuration with the proxy settings. This way you can have multiple proxies configured and disable proxy configuration with ease.

When behind a proxy

The agent supports working behind a proxy, but manual configuration is required (there is no support for automatic proxy discovery).

To add proxy configuration, create an additional configuration file (e.g. proxy.ini) with content:

name = Proxy Enabled
[env]
httpProxy="your.proxy.here"
httpsProxy="your.https.proxyhere"
  • Please note, spaces are not allowed before and after the string httpProxy Remember to restart the agent and to select the proper Proxy profile, as in the image.

Your agent will now work behind a proxy.

How to use a custom Private/Public key

Important

Make sure you have the Arduino Cloud Agent version >= 1.7.0

The Arduino Cloud Agent verifies commands before executing them. This verification is based on public/private key pairs to ensure that only commands signed with the Arduino private key can be executed, preventing arbitrary commands from running.

The private key is securely managed by Arduino and is used to generate the signature for commands. The Cloud Agent then uses the corresponding public key to verify the signature.

If you want to use the Arduino Cloud Agent with your own public/private key pair, follow these steps:

  1. Generate Public/Private Key Pairs. You can generate a key pair using OpenSSL:

    # Create a private key
openssl genrsa -out private.pem 2048

# Extract the public key from the private key
openssl rsa -pubout -in private.pem -out public.pem

  2. Find the config.ini file (refer to the configuration file location for details).

  3. Open config.ini and paste the contents of public.pem into the signatureKey field. Below is an example of a public key entry:

    signatureKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtHP52M8dCYDGaC4UaOvU
cfLqhteGX75EnbXMr6iOg7r7Of+doFV+Ee233Ly/di15CXaju3EpgUka5QSu6z2m
4sne32aGw6T/eggY636CKcRHFPFjLmXX0CHq+Evg3E4g8W7Yslo2qu1SP3ySZCqe
VpZHSeehlxFPpQKWXa1YiNF0gWh3cNQ0wneOsJ+ndShSuQ5C2YnSEoeoiEGVFOS0
evX4GEdadudGBjHQUKjhj+k3Ydaz014aIIC7CUVkQog9B7vpB+znHJH/gCl9DqYO
4mjPfHG4c5ppNu455hEe75R5q9bPc7TjBA3jpZsdrBY05lX2Q2nAQgSYIHpf78xl
7wIDAQAB
-----END PUBLIC KEY-----`

Note

The public key must be copied into the config.ini file inside backtick markers.

  1. After updating the configuration file, restart the agent to apply the changes.

  2. Use the private.pem key to generate the signature of your commands and send them where requested (e.g., POST /upload request)

Caution

Keep the private.pem file secure and never share it publicly.

Clone this wiki locally