Connect a provider

CrossXCloud reaches your cloud accounts using credentials you store in a local, passphrase-sealed vault. Connect at least one provider before you can build on the canvas.

What CrossXCloud expects

Provider	Credential type	What you paste into CrossXCloud
Hetzner	API token	A single token string with read and write scope
Google Cloud	Service account key	A JSON file downloaded from the Google Cloud console
AWS	Access key, assumed role, or named profile	An access key and secret (with an optional session token), or a role ARN to assume, or the name of a profile from your local AWS configuration
Azure	App registration client secret	A tenant ID, client ID, client secret, and subscription ID

CrossXCloud tags every resource it creates with a managed-by=crossxcloud label and a crossxcloud-node label that maps back to the canvas node. Your credential needs enough scope to read and write resources with these labels.

1. Unlock the vault

If the app just launched, unlock your vault with your passphrase. The vault status control in the top bar shows whether it is locked or unlocked.

You can save a credential while the vault is locked (saving only needs the public key), but you cannot use it until the vault is unlocked. See Credentials and the vault for the full lifecycle.

2. Create a credential on your provider

Hetzner

What you need

A Hetzner Cloud API token with read and write scope. Hetzner uses a single project-scoped token, not a key pair or OAuth flow.

Create the token

1. Open the Hetzner Cloud Console and sign in.
2. Select or create a project. CrossXCloud will manage resources within this project.
3. In the project sidebar, go to Security and then API Tokens.
4. Click Generate token.
5. Give the token a name you will recognize later, such as crossxcloud.
6. Set the permissions to Read & Write. CrossXCloud needs write access to create, update, and delete servers, networks, and floating IPs.
7. Click Generate token and copy the token. It is shown only once.

Save it in CrossXCloud

Open the Cloud Connections page in CrossXCloud, select Hetzner, and paste the token into the API token field. CrossXCloud validates the token immediately with a read-only call to the Hetzner API. If the token is invalid or lacks the right scope, you see an error before you try to build anything.

Google Cloud

What you need

A Google Cloud service account key (JSON) with permission to manage Compute Engine instances, VPC networks, firewall rules, and static external IP addresses. CrossXCloud extracts the GCP project ID from the JSON automatically.

Enable the required APIs

1. Open the Google Cloud Console and select or create a project.
2. Go to APIs & Services and then Library.
3. Enable the Compute Engine API. This covers instances, machine types, images, zones, networks, subnets, firewalls, and addresses.

Create a service account

1. Go to IAM & Admin and then Service Accounts.
2. Click Create service account.
3. Give it a name you will recognize later, such as crossxcloud.
4. Click Create and continue.
5. Grant the service account the roles it needs. CrossXCloud manages compute instances, networks, firewalls, and addresses, so the account needs broad Compute Engine access. The Compute Admin role (roles/compute.admin) covers all of these. If you prefer least-privilege, you can grant a combination of more specific roles:
   • Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) for instances
   • Compute Network Admin (roles/compute.networkAdmin) for networks, subnets, and firewalls
   • Compute Security Admin (roles/compute.securityAdmin) for firewall rules
6. Click Continue and then Done.

Create and download the key

1. In the service accounts list, click on the account you just created.
2. Go to the Keys tab.
3. Click Add key and then Create new key.
4. Select JSON as the key type and click Create.
5. A JSON file downloads to your machine. This is the credential.

Save it in CrossXCloud

Open the Cloud Connections page in CrossXCloud, select Google Cloud, and paste the full contents of the downloaded JSON file into the credential field. CrossXCloud parses the JSON and extracts the project ID automatically.

AWS

What you need

An AWS access key with permission to manage EC2 instances, VPC networking (subnets, security groups), and Elastic IP addresses. CrossXCloud also supports authenticating by assuming an IAM role, or by using a named profile from your local AWS configuration, if you would rather not store a long-lived key.

Create an access key

1. Open the IAM console and sign in.
2. Create or choose an IAM user for CrossXCloud, and grant it permission to manage EC2 instances, VPC networking, and Elastic IP addresses.
3. Open the user, go to Security credentials, and click Create access key.
4. Choose the use case that matches a third-party application, then click Create access key.
5. Copy the access key ID and secret access key. The secret is shown only once.

Save it in CrossXCloud

Open the Cloud Connections page in CrossXCloud, select AWS, and choose a credential method:

• Keys, the default: paste the access key ID and secret access key. Add a session token only if the credential you pasted is temporary. Set a region, or leave it blank to default to us-east-1.
• Assume role: paste a base access key (or select a profile) and the ARN of the role CrossXCloud should assume. CrossXCloud uses session name crossxcloud unless you set your own.
• Profile: give the name of a profile already configured in your local AWS config and credentials files.

Azure

What you need

An Azure app registration (a service principal) with permission to manage virtual machines, virtual networks, network security groups, and public IP addresses in the subscription CrossXCloud will use, and that subscription’s ID. Every Azure Resource Manager call CrossXCloud makes is scoped to a single subscription.

Create an app registration and client secret

1. Open the Azure portal and go to Microsoft Entra ID, then App registrations.
2. Click New registration, give it a name such as crossxcloud, and register it.
3. From the registration’s Overview, note the Application (client) ID and Directory (tenant) ID.
4. Go to Certificates & secrets, click New client secret, and copy the secret’s value. It is shown only once and expires on the date you set when creating it.
5. Grant the app registration a role, scoped to the subscription, that covers managing virtual machines, virtual networks, network security groups, and public IP addresses.
6. Note the subscription ID from the Subscriptions page in the portal.

Save it in CrossXCloud

Open the Cloud Connections page in CrossXCloud, select Azure, and paste the tenant ID, client ID, client secret, and subscription ID.

3. Confirm the connection

The connections list shows the providers you have saved. A saved credential is usable the moment the vault is unlocked.

When you open a project canvas, CrossXCloud reads your current infrastructure from the connected provider and lays it out as nodes. This is your starting state. From there everything you do is an edit on top of it.

Step	What happens	Where the credential is
Save	You paste a token or key. It is encrypted with the vault public key.	Encrypted blob in the keystore on disk.
Use	Plan or Apply needs the credential. The vault decrypts it in memory.	Plaintext in memory only, never written to disk.
Lock	You lock the vault or close the app. The private key is cleared.	Encrypted blob stays on disk, unusable until next unlock.

Test the connection

After saving a credential, use the Test action on the connection card. CrossXCloud makes a read-only call to the provider to confirm the credential works and has the right scope.

For Hetzner, this happens automatically when you save (the token is validated on save). For Google Cloud, the test call confirms the service account can reach the Compute Engine API for the project in the JSON. For AWS, saving keys, an assumed role, or a profile resolves the credential locally, but only the Test action makes a real STS call, which is the only way to prove a pasted session token is still alive rather than merely well-formed. For Azure, the test requests an Azure Resource Manager token for the subscription, which catches a client secret that has already expired.

If the test fails, check:

• The credential has not expired or been revoked on the provider side.
• The required APIs are enabled (GCP).
• The token or key has read and write scope.
• For AWS, a session token or assumed role has not expired since it was pasted.
• For Azure, the client secret has not passed the expiry date set when it was created.

Rotate a credential

To rotate a credential, create a new one on the provider side, save it in CrossXCloud, and delete the old one from the connections list. The next Plan and Apply uses the new credential.

You do not need to re-lock or recreate the vault to rotate a credential. The vault guards the key that encrypts credentials, not the credentials themselves. See Credentials and the vault.

What happens to your credentials

Your credentials stay on your machine, sealed in the keystore, and are decrypted only in memory while the vault is unlocked. They are never sent to CrossXCloud, to CrossXWeb, or to any third party. The canvas talks to your cloud directly using them. This is the core security model, explained in Security and the vault.

Next

With a provider connected, continue to Your first canvas to drag a node, join a network, and apply your first change.